4

我知道 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 中编写“文档字符串”的方法的答案。它不需要很长，足以帮助读者在他们的代码中使用这种“合同+文档字符串”模式（并且可能描述其他替代方案）。

4

1 回答 1

4

你想要at-exp“元语言”。这使您可以使用另一种语言进行编程（在这种情况下racket，通过使用 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第一行中的。

你也可以这样做：

#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" ...)) ...)
于 2019-11-21T20:09:17.057 回答