"Docstrings" 在球拍中？

Question

我知道 Racket 没有像许多其他语言那样的 "docstrings"，但是考虑到在源头记录内容是多么方便，我想在 Racket 中近似类似的东西。

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

#lang racket
#lang scribble

... 然后在 Racket 中使用文档字符串在 Scribble 中编写代码。但是这样不行，可能是因为"languages don't compose."

#lang racket
(require scribble/manual)

@racket['hi]

这导致：

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

我发现 scribble/srcdoc which seems compelling because it sounds like it allows you to piggyback docs on top of contracts 除了提供运行时检查之外，它已经作为一种最小的（通常是模块级的）文档。到目前为止我还没能让它工作，但我认为在这里询问它会更有用，而不是再折腾几个小时。对于它的价值，这是我目前看到的：

#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))

由于像 these 这样的参考文档更擅长解释事物是如何工作的，而不是如何使用它，我正在寻找一个更像是如何编写 "docstrings" 的答案球拍。它不需要很长，足以帮助 reader 在他们的代码中使用这种 "contract + docstring" 模式（并且可能描述其他替代方案）。

Answer 1

您想要 at-exp 'meta-language'。这使您可以使用另一种语言进行编程（在本例中 racket，并修改了使用 at 表达式。

所以以你上面的例子为例，你得到：

#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。

您还可以这样做：

#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" ...)) ...)

"Docstrings" 在球拍中？

"Docstrings" in Racket?

racket

docstring

scribble