Next: 注释编写技巧, Previous: 避免编译器警告的技巧, Up: 技巧与规范   [Contents][Index]

---

D.6 文档字符串编写技巧 ¶

本节介绍文档字符串的编写技巧与规范。运行命令 M-x checkdoc-minor-mode 可检查其中大部分规范。

• 所有面向用户的命令、函数或变量都应配有文档字符串。
• Lisp 程序的内部变量或子程序也建议添加文档字符串。 文档字符串在 Emacs 运行时占用空间极小。
• 格式化文档字符串，使其适配 80 列宽度的 Emacs 窗口。 大多数行建议不超过 60 字符。首行不应超过 74 字符，否则在 apropos 输出中显示效果不佳。

  文本排版美观时可自动换行。Emacs Lisp 模式会按照 emacs-lisp-docstring-fill-column 指定宽度对文档字符串换行。 不过，精心调整换行位置往往能大幅提升可读性。 若文档字符串较长，可在段落间使用空行分隔。

• 文档字符串首行应由一到两句独立成意的总结性完整语句构成。 M-x apropos 仅显示首行，若首行表意不完整会影响展示效果。 首行需以大写字母开头、句号结尾。

  对函数而言，首行应简要回答 “该函数做什么？”；对变量而言，首行应简要回答 “该值含义是什么？”。 表述应面向用户与调用者，易于理解。 特别注意：不要通过罗列代码行为描述函数功能，而应说明这些行为的作用与函数约定。

  文档字符串不必仅限一行，可使用多行详细说明函数或变量的使用方法。 其余文本也请使用完整语句。

• 当用户尝试使用禁用的命令时，Emacs 仅显示其文档字符串的第一段，即到第一个空行之前的所有内容。 如有需要，可合理安排首行空行前的内容，让该展示更有用。
• 首行应提及函数所有重要参数（尤其是必选参数），并按函数调用顺序排列。 若参数过多，无法在首行全部列出，则应列出前几个及最重要的参数。
• 函数文档字符串提及参数值时，将参数名大写，作为该值的代称。 例如函数 eval 的文档将其第一个参数称为 ‘FORM’，因其实际参数名为 form：

  Evaluate FORM and return its value.
  

  元语法变量也应大写，例如将列表或向量拆分为可变子单元时的表示。 下例中的 ‘KEY’ 和 ‘VALUE’ 即为该写法：

  The argument TABLE should be an alist whose elements
  have the form (KEY . VALUE).  Here, KEY is ...
  

• 在文档字符串中提及 Lisp 符号时，切勿改变其大小写。 若符号名为 foo，应写作 “foo”，而非 “Foo”（后者是另一个符号）。

  这看似与函数参数值的写法规范冲突，实则并不矛盾：参数 值 与函数用于保存该值的 符号 并非同一事物。

  若因此导致句子以小写字母开头，可重写句子，避免将符号置于句首。

• 不要在文档字符串开头或结尾使用空白字符。
• 不要为了让源码中文本与首行对齐而缩进文档字符串后续行。 这种写法在源码中美观，但用户查看文档时会显得怪异。 记住：起始双引号前的缩进不属于字符串内容！
• 文档需要显示 ASCII 单引号或反引号时，在字符串字面值中使用 ‘\\='’ 或 ‘\\=`’，以保证字符原样显示。
• 文档字符串中，非 Lisp 符号的表达式无需加引号，可直接表示自身。 例如，写作 ‘Return the list (NAME TYPE RANGE) ...’， 而非 ‘Return the list `(NAME TYPE RANGE)' ...’ 或 ‘Return the list \\='(NAME TYPE RANGE) ...’。
• 文档字符串引用 Lisp 符号时，按其打印形式书写（通常为小写），并在前后分别添加反引号 ‘`’ 与单引号 ‘'’。 两个例外：t 和 nil 不加标点。示例：

  CODE can be `lambda', nil, or t.
  

  注意 Emacs 显示文档字符串时，若终端支持，通常会将 ‘`’ 显示为左单引号 ‘‘’，‘'’ 显示为右单引号 ‘’’。See 文档中的按键绑定替换。 （本节旧版曾建议直接在文档字符串中使用非 ASCII 单引号，现已不推荐，因其会在不支持该字符的终端上导致帮助显示异常。）

  当文档字符串使用带单引号的符号名，且该符号存在函数或变量定义时，帮助模式会自动创建超链接。 使用该功能无需额外操作。 但若符号同时有函数与变量定义，而你只想指向其中一个，可在符号名前添加 ‘variable’、‘option’、‘function’ 或 ‘command’ 以指定类型（大小写不敏感）。例如：

  This function sets the variable `buffer-file-name'.
  

  此时超链接将仅指向 buffer-file-name 的变量文档，而非函数文档。

  若符号虽有函数或变量定义，但与当前文档内容无关，可在符号名前添加 ‘symbol’ 或 ‘program’ 以禁止生成超链接。例如：

  If the argument KIND-OF-RESULT is the symbol `list',
  this function returns a list of all the objects
  that satisfy the criterion.
  

  该写法不会链接到函数 list 的无关文档。

  通常，无文档的变量不会生成超链接。 可在其前添加 ‘variable’ 或 ‘option’ 强制生成超链接。

  文本的视觉样式（face）仅在名称前后带有 ‘face’ 一词时才生成超链接，此时仅显示其样式文档，即使该符号同时被定义为变量或函数。

  若要链接到 Info 文档，可在 Info 节点（或锚点）的单引号名称前添加 ‘info node’、‘Info node’、‘info anchor’ 或 ‘Info anchor’。 Info 文件名默认为 ‘emacs’。示例：

  See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
  

  若要链接到手册页，可在手册页单引号名称前添加 ‘Man page’、‘man page’ 或 ‘man page for’。示例：

  See the man page `chmod(1)' for details.
  

  Info 文档优先级高于手册页，如有可用的 Info 手册请优先链接。 例如 chmod 文档位于 GNU Coreutils 手册中，应优先链接该手册而非手册页。

  若要链接到自定义组，可在组的单引号名称前添加 ‘customization group’（单词首字母大小写不限）。示例：

  See the customization group `whitespace' for details.
  

  最后，若要创建 URL 超链接，可在单引号 URL 前添加 ‘URL’。示例：

  The GNU project website has more information (see URL
  `https://www.gnu.org/').
  

• 不要在文档字符串中直接书写按键序列，应使用 ‘\\[…]’ 结构表示。 例如，不写 ‘C-f’，而写 ‘\\[forward-char]’。 Emacs 显示文档时会自动替换为当前绑定到 forward-char 的按键（通常为 ‘C-f’，用户修改按键绑定后可能变化）。See 文档中的按键绑定替换。
• 主模式的文档字符串需要引用该模式局部按键映射而非全局映射。 因此，应在文档字符串中首次使用 ‘\\[…]’ 之前，使用一次 ‘\\<…>’ 指定所用按键映射，且不要放在句子中间（若映射未加载，对映射的引用会被替换为映射未定义的提示语句）。 ‘\\<…>’ 内部应为保存主模式局部按键映射的变量名。

  大量使用 ‘\\[…]’ 会轻微降低文档字符串显示速度，在慢速系统上累积后可能可感知。 因此建议不要过度使用，例如同一文档字符串中避免多次引用同一命令。

• 为保持一致，函数文档字符串首句动词使用祈使语气。 例如优先使用 “Return the cons of A and B.”，而非 “Returns the cons of A and B.”。 首段其余语句通常也采用相同风格。后续段落使用陈述语气并带有完整主语效果更佳。
• 判断真假的谓词函数文档字符串应以 “Return t if” 之类语句开头，明确说明真值条件。 使用 “return” 可避免句子以小写 “t” 开头导致的观感问题。
• 文档字符串使用主动语态、现在时态，避免被动语态与将来时态。 例如使用 “Return a list containing A and B.”，而非 “A list containing A and B will be returned.”。
• 避免不必要地使用 “cause”（或同义词汇）。 例如将 “Cause Emacs to display text in boldface” 简化为 “Display text in boldface”。
• 避免使用 “iff” （数学术语，意为 “当且仅当(if and only if)”），多数用户不熟悉该缩写并易误认为拼写错误。 多数场景下使用 “if” 即可表意清晰，否则可换用其他句式。
• 尽量避免使用 “e.g.”、“i.e.”、“no.”、“cf.”、“w.r.t.”等缩写，展开书写通常更清晰易读。³⁶
• 若命令仅在特定模式或场景下有效，请在文档字符串中说明。 例如 dired-find-file 的文档为：

  In Dired, visit the file or directory named on this line.
  

• 定义表示用户可设置选项的变量时，使用 defcustom。See 定义全局变量。
• 布尔开关变量的文档字符串应以 “Non-nil means” 之类语句开头，明确所有非 nil 值等效，并说明 nil 与非 nil 的含义。
• 若文档字符串某行以左括号开头，建议在括号前添加反斜杠，示例：

  The argument FOO can be either a number
  \(a buffer position) or a string (a file name).
  

  该写法可避免 27.1 版之前 Emacs 的缺陷，即 ‘(’ 会被识别为 defun 起始位置（see Defuns in The GNU Emacs Manual）。 若不考虑使用旧版 Emacs 编辑代码，则无需该兼容处理。