Группы документации

Emacs может составлять списки функций, объединённых по различным признакам. Например, string-trim и mapconcat — это строковые функции, поэтому команда M-x shortdoc RET string RET предоставит обзор этих и других функций для работы со строками.

Группы документации создаются с помощью макроса define-short-documentation-group. О том, как создавать хорошие группы документации, см. Советы по созданию групп документации.

Макрос: define-short-documentation-group group &rest functions

Определяет group как группу функций и предоставляет краткие примеры использования этих функций. Необязательный аргумент functions — это список, элементы которого имеют следующий вид:

(func [keyword val]...)

Распознаются следующие ключевые слова:

:eval

Значением должно быть выражение, вычисление которого не вызывает побочных эффектов. Это выражение будет использоваться в документации: оно будет напечатано с помощью prin1 (см. Функции вывода). Однако если выражение является строкой, оно будет вставлено без изменений, а затем строка будет 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")))

Первый аргумент — имя определяемой группы, за которым следует любое количество описаний функций.

Функция может входить в любое количество групп документации.

Помимо описаний функций, список также может содержать строковые элементы, которые используются для разделения группы документации на секции.

Функция: shortdoc-add-function group section elem

Пакеты Lisp могут добавлять функции в группы с помощью этой функции. Каждый elem должен быть описанием функции, как описано выше. group — это группа функций, а section — секция группы функций, в которую следует вставить функцию.

Если group не существует, она будет создана. Если section не существует, она будет добавлена в конец группы функций.

Можно также запрашивать примеры использования функций, определённых в группах shortdoc.

Функция: shortdoc-function-examples function

Эта функция возвращает все примеры shortdoc для function. Возвращаемое значение — это alist с элементами вида (group . examples), где group — группа документации, в которой встречается function, а examples — строка с примерами использования function, определёнными в group.

shortdoc-function-examples возвращает nil, если function не является функцией или для неё нет примеров shortdoc.

Функция: shortdoc-help-fns-examples-function function

Эта функция запрашивает зарегистрированные группы shortdoc и вставляет в текущий буфер примеры использования заданной функции Emacs Lisp function. Её можно добавить в обработчик help-fns-describe-function-functions; в этом случае примеры использования функции из shortdoc будут отображаться в буфере *Help* при запросе документации этой функции.