Строки документации функций

Лямбда-выражение может необязательно содержать строку документации сразу после списка лямбда-параметров. Эта строка не влияет на выполнение функции; это своего рода комментарий, но систематизированный комментарий, который фактически находится внутри мира Lisp и может использоваться средствами справки Emacs. О том, как получить доступ к строке документации, см. раздел Документация.

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

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

Начало строки документации обычно имеет отступ в исходном файле, но поскольку эти пробелы стоят перед открывающей двойной кавычкой, они не являются частью строки. Некоторые предпочитают добавлять отступ к дополнительным строкам строки документации, чтобы текст выравнивался в исходном коде программы. Это ошибка. Отступы последующих строк входят в строку; то, что хорошо выглядит в исходном коде, будет плохо смотреться при отображении командами справки.

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

В последней строке строки документации можно указать соглашения о вызове, отличающиеся от фактических аргументов функции. Напишите, например, такой текст:

\(fn arglist)

после пустой строки, в начале строки, без следующего за ним символа новой строки внутри строки документации. (Символ ‘\’ используется, чтобы избежать конфликтов с командами перемещения Emacs.) Указанное таким образом соглашение о вызове отображается в сообщениях справки вместо соглашения, выведенного из фактических аргументов функции.

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

Не используйте эту возможность, если хотите объявить соглашение о вызове устаревшим и отдать предпочтение соглашению, указанному выше. Вместо этого используйте объявление advertised-calling-convention (см. раздел Форма declare) или set-advertised-calling-convention (см. раздел Объявление функций устаревшими), поскольку оба этих способа заставят байт-компилятор вывести предупреждение при компиляции программ Lisp, использующих устаревшее соглашение о вызове.

Возможность (fn) обычно используется в следующих случаях:

• Чтобы перечислить аргументы и объяснить их назначение в макросе или функции. Пример:

  (defmacro lambda (&rest cdr)
    "...
  \(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"...)
  

• Чтобы предоставить более подробное описание и имена аргументов. Пример:

  (defmacro macroexp--accumulate (var+list &rest body)
    "...
  \(fn (VAR LIST) BODY...)"
    (declare (indent 1))
    (let ((var (car var+list))
  	  (list (cadr var+list))
  ...)))
  

• Чтобы лучше объяснить назначение defalias. Пример:

  (defalias 'abbrev-get 'get
    "...
  \(fn ABBREV PROP)")
  

Строки документации обычно статичны, но иногда может потребоваться генерировать их динамически. В некоторых случаях это можно сделать, написав макрос, который во время компиляции генерирует код функции, включая нужную строку документации. Однако можно также генерировать строку документации динамически, указав (:documentation form) вместо строки документации. При определении функции это вычислит form во время выполнения и использует результат в качестве строки документации. Можно также вычислять строку документации непосредственно в момент запроса, присвоив свойству function-documentation символа функции форму Lisp, результатом вычисления которой является строка.

Например:

(defun adder (x)
  (lambda (y)
    (:documentation (format "Add %S to the argument Y." x))
    (+ x y)))
(defalias 'adder5 (adder 5))
(documentation 'adder5)
    ⇒ "Add 5 to the argument Y."

(put 'adder5 'function-documentation
     '(concat (documentation (symbol-function 'adder5) 'raw)
              "  Consulted at " (format-time-string "%H:%M:%S")))
(documentation 'adder5)
    ⇒ "Add 5 to the argument Y.  Consulted at 15:52:13"
(documentation 'adder5)
    ⇒ "Add 5 to the argument Y.  Consulted at 15:52:18"