Основы документации

Строка документации записывается с использованием синтаксиса Lisp для строк: текст заключается в двойные кавычки. Фактически это обычная строка Lisp. Если строка находится в соответствующем месте определения функции или переменной, она служит документацией этой функции или переменной.

В определении функции (форме lambda или defun) строка документации указывается после списка аргументов и обычно хранится непосредственно в объекте функции. См. Строки документации функций. Документацию функции также можно поместить в свойство function-documentation имени функции (см. Доступ к строкам документации).

В определении переменной (форме defvar) строка документации указывается после начального значения. См. Определение глобальных переменных. Строка хранится в свойстве variable-documentation переменной.

Иногда Emacs не хранит строки документации в памяти. Это происходит в двух случаях. Во-первых, для экономии памяти документация примитивных функций (см. Что такое функция?) и встроенных переменных хранится в файле с именем DOC в каталоге, заданном параметром doc-directory (см. Доступ к строкам документации). Во-вторых, когда функция или переменная загружается из байт-компилируемого файла, Emacs не загружает её строку документации (см. Строки документации и компиляция). В обоих случаях Emacs извлекает строку документации из файла только при необходимости, например, когда пользователь вызывает C-h f (describe-function) для функции.

Строки документации могут содержать специальные последовательности подстановки клавиш, указывающие на привязки клавиш, которые определяются только при просмотре документации пользователем. Благодаря этому команды справки отображают правильные клавиши, даже если пользователь изменил привязки клавиш по умолчанию. См. Подстановка привязок клавиш в документации.

В строке документации автоматически загружаемой команды (см. Автоматическая загрузка) эти последовательности подстановки клавиш имеют дополнительный особый эффект: они приводят к автоматической загрузке команды при вызове C-h f для неё. (Это необходимо для правильной настройки гиперссылок в буфере *Help*.)