Racket(Scheme)中的源代码文档



是否可以在源文件中编写文档,例如在Common Lisp或Go中,并从源文件中提取文档?或者每个人都使用Scribble来记录他们的代码?

简单的答案是,您可以使用scribble/srcdoc在源文档中编写。

与您提到的其他语言不同,这些语言不是"文档字符串":

  • 尽管您可以编写纯文本,但您在表达式上有完整的Racket,并且可以使用scribble/manual形式和函数。

  • 这不仅允许"更丰富"的文档,文档还进入自己的文档子模块——类似于如何将测试放入test子模块。这意味着文档或测试不增加运行时开销。

您确实需要一个.scrbl文件,在该文件中使用scribble/extract来包含文档子模块。然而,无论如何,您可能想要这样一个文件,用于非功能特定的文档(主题如介绍、安装或"用户指南"散文,而不是"参考"风格的文档)。

当然,您可以定义自己的语法来包装scribble/srcdoc。例如,在一个项目中,我定义了一个小的define/doc宏,它可以扩展为proc-doc/names(module+ test ___)形式。这样,文档示例也可以用作单元测试。

Racket如何处理源文档与Racket:的几个有趣方面交叉

  • 子模块允许您定义诸如"测试时间"one_answers"文档时间"以及运行时之类的内容。

  • At表达式是s表达式的一种不同语法,尤其适用于编写文本。

  • Scrible是一个使用自定义语言(文档即程序)的例子,它展示了Racket不仅是一种编程语言,而且是一种程序设计语言的能力。

最新更新