---

25.7 Documentation Groups

Emacs can list functions based on various groupings. For instance, string-trim and mapconcat are “string” functions, so M-x shortdoc RET string RET will give an overview of functions that operate on strings.

The documentation groups are created with the define-short-documentation-group macro.

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

Define group as a group of functions, and provide short summaries of using those functions. The optional argument functions is a list whose elements are of the form:

(func [keyword val]…)

The following keywords are recognized:

:eval

The value should be a form that has no side effect when evaluated. The form will be used in the documentation by printing it with prin1 (see Output Functions). However, if the form is a string, it will be inserted as-is, and the string will then be read to yield the form. In any case, the form will then be evaluated, and the result used. For instance:

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

will result in:

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

(The reason for allowing both Lisp forms and strings here is so that printing could be controlled in the few cases where a certain presentation of the form is wished for. In the example, ‘?x’ would otherwise have been printed as ‘120’ if it hadn’t been included in a string.)

:no-eval

This is like :eval, except that the form will not be evaluated. In these cases, a :result element of some kind (see below) should be included.

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

:no-eval*

Like :no-eval, but always inserts ‘[it depends]’ as the result. For instance:

:no-eval* (buffer-string)

will result in:

(buffer-string)
→ [it depends]

:no-value

Like :no-eval, but is used when the function in question has no well-defined return value, and is used for side effect only.

:result

Used to output the result from non-evaluating example forms.

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

:eg-result

Used to output an example result from non-evaluating example forms. For instance:

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

will result in:

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

:result-string

:eg-result-string

These two are the same as :result and :eg-result, respectively, but are inserted as is. This is useful when the result is unreadable or should be of a particular form:

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

:no-manual

Indicates that this function is not documented in the manual.

:args

By default, the function’s actual argument list is shown. If :args is present, they are used instead.

:args (regexp string)

Here’s a very short example:

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

The first argument is the name of the group to be defined, and then follows any number of function descriptions.

A function can belong to any number of documentation groups.

In addition to function descriptions, the list can also have string elements, which are used to divide a documentation group into sections.

Function: shortdoc-add-function group section elem ¶

Lisp packages can add functions to groups with this function. Each elem should be a function description, as described above. group is the function group, and section is what section in the function group to insert the function into.

If group doesn’t exist, it will be created. If section doesn’t exist, it will be added to the end of the function group.