Question

我知道Racket并不像许多其他语言一样具有“文档字符串”，但是鉴于从源头上记录事物的便捷性，我想在Racket中进行类似的估算。

当我第一次学习Scribble和#langs时，我认为可以做类似的事情：

#lang racket
#lang scribble

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

#lang racket
(require scribble/manual)

@racket['hi]

结果为：

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

我碰到了scribble/srcdoc，这似乎很引人注目，因为它听起来像可以让您在contracts之上back带文档，这些文档已经作为一种最小（通常是模块级）文档，当然提供运行时检查。到目前为止，我还无法使它正常工作，但是与其再花几个小时的时间，我认为在这里询问它会更有用。对于它的价值，这是我目前所看到的：

#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中编写“文档字符串”的方法。不必太长，仅足以帮助读者在其代码中使用这种“合同+文档字符串”模式（并可能描述其他替代方法）。

Answer 1

您需要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" ...)) ...)

球拍中的“文档字符串”？

1 个答案: