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

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

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

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

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

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

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