Question

我已经搜索了一些诸如“lisp文档字符串”，“lisp评论”和其他一些内容，我找不到任何具体解决此问题的内容。

我看到很多代码（特别是在CL和elisp中）看起来像

(defvar test 1
  "This is a quoted string and it says things"
)

我通常会去哪里

; This is a comment
(defvar test 1)

哪个更受欢迎？每个都有不同的用途吗？谢谢！

Answer 1

Common Lisp中的许多对象都可以有一个文档字符串，可以使用泛型函数documentation进行检索，并使用泛型函数(setf documentation)进行设置。根据{{3}}：

文档字符串可用于调试目的。允许合规程序在文档字符串存在时使用它们，但不应依赖于它们在存在这些文档字符串时的正确行为。由于实现定义的原因，允许实施随时丢弃文档字符串。

因此，第一种情况允许定义变量及其文档字符串，可用于在运行时存储，如果实现允许，则可用于文档和调试目的的信息，或者通过IDE使用，或直接通过以下形式：

(documentation 'test 'variable)

第二种情况只是源文件中的注释，仅对人类消费有用，并且系统的读者/编译器完全忽略它。

Answer 2

开发环境将使用这些文档功能。例如GNU Emacs / SLIME：

将文本光标移动到符号test上。

键入 c-c c-d c-d （描述符号）。

现在SLIME显示一个包含以下内容的缓冲区：

COMMON-LISP-USER::TEST
  [symbol]

TEST names a special variable:
  Value: 1
  Documentation:
    This is a quoted string and it says things

源代码中的简单注释不会启用这种形式的开发环境集成和文档查找。

Answer 3

我看到你的标签包括方案和elisp。在CL和Elisp中总是使用docstrings。文档系统以其语言使用它们。 Scheme没有该功能，因此您必须继续使用注释来记录函数。

Answer 4

你没试过看defvar的超标准吗？

defvar采用可选参数 - 文档字符串，这就是你在说什么。

以这种方式指定的文档可以通过documentation：

获取

CL-USER> (defvar *a* "A variable" "A docstring")
*A*
CL-USER> (documentation '*a* 'variable)
"A docstring"