Previous: 帮助函数, Up: 文档   [Contents][Index]

25.7 文档分组 ¶

Emacs 可以按照不同分组列出函数。例如，string-trim 和 mapconcat 都属于“字符串”函数， 因此执行 M-x shortdoc RET string RET 可以概览所有操作字符串的函数。

文档分组通过 define-short-documentation-group 宏定义。

Macro: define-short-documentation-group group &rest functions ¶

将 group 定义为一个函数分组，并提供这些函数的简要用法说明。可选参数 functions 是一个列表， 每个元素格式如下：

(func [keyword val]...)

The following keywords are recognized:

:eval

取值应为一个求值时无副作用的表达式。该表达式会通过 prin1 打印并显示在文档中（see 输出函数）。 如果表达式是字符串，则会原样插入，之后再通过 read 解析为表达式。无论哪种形式，最终都会被求值并展示结果。例如：

:eval (concat "foo" "bar" "zot")
:eval "(make-string 5 ?x)"

会生成如下显示：

(concat "foo" "bar" "zot")
⇒ "foobarzot"
(make-string 5 ?x)
⇒ "xxxxx"

（此处同时支持 Lisp 表达式和字符串，是为了在少数需要精确控制表达式展示形式的场景下使用。 例如上例中，如果不放在字符串里，‘?x’ 会被打印成 ‘120’。）

:no-eval

与 :eval 类似，但不会对表达式求值。这种情况下通常需要搭配某种 :result 系列关键字（见下文）。

:no-eval (file-symlink-p "/tmp/foo")
:eg-result t

:no-eval*

与 :no-eval 类似，但结果固定显示为 ‘[it depends]’。例如：

:no-eval* (buffer-string)

会生成：

(buffer-string)
→ [it depends]

:no-value

与 :no-eval 类似，用于函数没有明确定义返回值、仅用于产生副作用的场景。

:result

用于为不求值的示例表达式指定输出结果。

:no-eval (setcar list 'c)
:result c

:eg-result

用于为不求值的示例表达式输出示例结果。例如：

:no-eval (looking-at "f[0-9]")
:eg-result t

会生成：

(looking-at "f[0-9]")
eg. → t

:result-string

:eg-result-string

分别与 :result 和 :eg-result 作用相同，但会原样插入字符串。 适用于结果不可读或需要特定格式的场景：

:no-eval (find-file "/tmp/foo")
:eg-result-string "#<buffer foo>"
:no-eval (default-file-modes)
:eg-result-string "#o755"

:no-manual

表示该函数未在手册中专门说明。

:args

默认显示函数实际的参数列表。如果指定了 :args，则使用此处给出的参数列表。

:args (regexp string)

一个极简示例：

(define-short-documentation-group string
  "Creating Strings"
  (substring
   :eval (substring "foobar" 0 3)
   :eval (substring "foobar" 3))
  (concat
   :eval (concat "foo" "bar" "zot")))

第一个参数是要定义的分组名称，之后可以跟随任意数量的函数说明。

一个函数可以属于任意多个文档分组。

除函数说明外，列表中还可以包含字符串元素，用于将一个文档分组划分为多个小节。

Function: shortdoc-add-function group section elem ¶

Lisp 包可以使用该函数向分组中添加函数。每个 elem 应为上文所述格式的函数说明。 group 为目标函数分组，section 为要插入到该分组中的小节名称。

如果 group 不存在，则会自动创建。如果 section 不存在，则会添加到函数分组的末尾。

你也可以查询在 shortdoc 分组中定义的函数用法示例。

Function: shortdoc-function-examples function ¶

该函数返回 function 的所有 shortdoc 示例。返回值为一个关联列表，元素格式为 (group . examples)，其中 group 是该函数所属的文档分组， examples 是一个字符串，包含该分组中定义的函数用法示例。

如果 function 不是函数，或者没有任何 shortdoc 示例，则 shortdoc-function-examples 返回 nil。

Function: shortdoc-help-fns-examples-function function ¶

该函数查询已注册的 shortdoc 分组，并将指定 Emacs Lisp 函数 function 的用法示例插入到当前框架中。 它适合添加到 help-fns-describe-function-functions 钩子中，这样在查看函数文档时， shortdoc 中的用法示例会显示在 *Help* 框架里。