Racket 中的“文档字符串”？

Question

我知道 Racket 没有像许多其他语言那样具有“文档字符串”，但考虑到在源代码中记录事物是多么方便，我想在 Racket 中近似类似的东西。

当我第一次了解 Scribble 和 #langs 时，我认为可以做如下事情：

#lang racket
#lang scribble

...然后在 Racket 中使用 Scribble 中的文档字符串编写代码。但这行不通，可能是因为“语言不会组合”。

#lang racket
(require scribble/manual)

@racket['hi]

结果是：

my-source.rkt:4:0: @racket: unbound identifier

我发现这似乎很引人注目，因为听起来它允许您在合同scribble/srcdoc之上搭载文档，这些文档已经作为一种最小（通常是模块级）文档，当然除了提供运行时检查之外。到目前为止我还没能让它工作，但我认为在这里询问它会更有用，而不是再折腾几个小时。就其价值而言，这就是我目前所看到的：

#lang racket
(require scribble/srcdoc
         (for-doc scribble/base scribble/manual))

(provide
 (proc-doc/names fib
                 (-> integer? integer?)
                 (n)
                 @{Computes the @racket[n]th Fibonacci number}))

(define (fib n)
  (if (< n 2)
      n
      (+ (fib (- n 1))
         (fib (- n 2)))))

结果是：

my-source.rkt:6:1: proc-doc/names: bad syntax
  in: (proc-doc/names fib (-> integer? integer?) (n) @ (Computes the @racket (n) th Fibonacci number))

由于像这样的参考文档更能解释事物是如何工作的而不是如何使用它，所以我正在寻找一个更像是在 Racket 中编写“文档字符串”的方法的答案。它不需要很长，足以帮助读者在他们的代码中使用这种“契约+文档字符串”模式（并且可能描述其他替代方案）。

Answer 1

您需要at-exp“元语言”。这使您可以使用另一种语言进行编程（在本例中racket, with the modification of using at-expressions.

因此，以上面的例子为例，您会得到：

#lang at-exp racket
(require scribble/srcdoc
         (for-doc scribble/base scribble/manual))

(provide
 (proc-doc/names fib
                 (-> integer? integer?)
                 (n)
                 @{Computes the @racket[n]th Fibonacci number}))

(define (fib n)
  (if (< n 2)
      n
      (+ (fib (- n 1))
         (fib (- n 2)))))

请注意at-exp in the first line.

您还可以这样做：

#lang at-exp racket
(require scribble/manual)

@racket['hi]

并得到：

(sized-element #f (list (cached-element #0=(style "RktVal" (list 'tt-chars (css-addition '(collects #"scribble" #"racket.css")) (tex-addition '(collects #"scribble" #"racket.tex")))) "'" ...) (cached-element #0# "hi" ...)) ...)