racket - Racket 中的"Docstrings"？

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 这似乎很有说服力，因为听起来它允许您在 contracts 之上搭载文档除了提供运行时检查之外，它已经作为一种最小(通常是模块级)文档。到目前为止，我还无法让它工作，但与其再折腾几个小时，我认为在这里询问它会更有用。对于它的值(value)，这就是我目前所看到的:

#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比如何使用它更善于解释事物是如何工作的，我正在寻找一个更多关于在 Racket 中编写“文档字符串”的方法的答案。它不需要很长，足以帮助读者在他们的代码中使用这种“契约(Contract)+文档字符串”模式(并且可能描述其他替代方案)。

Answer 1

你想要 at-exp “元语言”。这使您可以使用另一种语言进行编程(在本例中为 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" ...)) ...)