Racket &引用；“文档字符串”；吵闹？

我知道Racket不像其他语言那样有“docstring”，但考虑到在源代码处记录东西是多么方便，我想在Racket中使用类似的东西

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

#lang racket
#lang scribble

。。。然后在Racket中用Scribble中的docstring编写代码。但这不起作用，可能是因为“语言不构成”

其结果是：

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

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

我遇到了这一点，它看起来很有吸引力，因为它听起来像是让你能够在上面搭载文档，除了提供运行时检查之外，文档已经作为一种最小的（通常是模块级）文档。到目前为止，我还没能让它发挥作用，但我认为在这里询问它会更有用，而不是再浪费几个小时。值得一提的是，我现在看到的是：

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

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

您需要“元语言”。这允许您使用另一种语言（在本例中为

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

并获得：

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

---

这真是太好了！为什么在

proc/doc

示例中，语言是Racket而不是Scribble？感觉应该是

#lang Racket

来表示文件的语言，然后

#lang at exp Scribble

来表示在@expressions中使用哪种语言？我认为Scribble文档是h很难理解。我只是找到一个可写的涂鸦文件，然后学习如何使用它。在这篇文章中有很多细节无法回答。你可以从scrbble文件和html文件中学习。例如，我看到html有代码块，我用给定的关键字搜索所有scrbl文件，我无法理解如何使用它。你可以学习标题内容引用…很有意义，感谢@Tjorcht的现场报告！是的，Scribble文档看起来更像是“参考”风格而不是“指南”（不像Racket文档两者都有）。我确实试着做了一些你建议的事情，但是

scribble/srcdoc

可能是一种不太常见的方法，所以我找不到很多例子。如果这对下一个人有帮助，下面是一个包含一些合同级“docstring”示例的示例。相关：

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