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

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

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

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

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

Вы можете задаться вопросом, как строка документации может быть необязательной, так как за ней следуют обязательные компоненты функции (тело). Поскольку вычисление строки возвращает эту строку без каких-либо побочных эффектов, оно не имеет эффекта, если это не последняя форма в теле. Таким образом, на практике нет путаницы между первой формой тела и строкой документации; если единственная форма тела — это строка, то она служит как значение возврата, так и документацией.

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

\(fn arglist)

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

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

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