---

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

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

Группы документации создаются с помощью макроса define-short-documentation-group.

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

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

(func [keyword val]…)

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

:eval

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