---

D.6 Советы по строкам документации

Вот несколько советов и соглашений по написанию строк документации. Вы можете проверить многие из этих соглашений, выполнив команду M-x checkdoc-minor-mode.

• Каждая команда, функция или переменная, предназначенная для пользователей, должна иметь строку документации.
• Внутренняя переменная или подпрограмма программы на Lisp также может иметь строку документации. Строки документации занимают очень мало места в работающем Emacs.
• Форматируйте строку документации так, чтобы она помещалась в окне Emacs на 80-колонном экране. Желательно, чтобы большинство строк были не шире 60 символов. Первая строка не должна быть шире 74 символов, иначе она будет плохо выглядеть в выводе apropos.

  Вы можете заполнять текст, если это выглядит хорошо. Режим Emacs Lisp заполняет строки документации до ширины, заданной emacs-lisp-docstring-fill-column. Однако иногда можно сделать строку документации гораздо более читаемой, тщательно расставляя разрывы строк. Используйте пустые строки между разделами, если строка документации длинная.

• Первая строка строки документации должна состоять из одного-двух законченных предложений, которые сами по себе служат кратким описанием. M-x apropos отображает только первую строку, и если её содержимое не является самодостаточным, результат выглядит плохо. В частности, начинайте первую строку с заглавной буквы и заканчивайте её точкой.

  Для функции первая строка должна кратко отвечать на вопрос: «Что делает эта функция?» Для переменной первая строка должна кратко отвечать на вопрос: «Что означает это значение?» Старайтесь отвечать на эти вопросы так, чтобы ответ был понятен пользователям и вызывающим функцию или переменную. В частности, не описывайте, что делает функция, перечисляя действия её кода; вместо этого описывайте роль этих действий и контракт функции.

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

• Когда пользователь пытается использовать отключённую команду, Emacs отображает только первый абзац её строки документации — всё до первой пустой строки. При желании вы можете выбрать, какую информацию включать до первой пустой строки, чтобы сделать этот вывод полезным.
• Первая строка должна упоминать все важные аргументы функции (в частности, обязательные) и упоминать их в том порядке, в котором они записываются в вызове функции. Если у функции много аргументов, упомянуть их все в первой строке невозможно; в этом случае первая строка должна упоминать первые несколько аргументов, включая самые важные.
• Когда в строке документации функции упоминается значение аргумента, используйте имя аргумента заглавными буквами, как если бы это было имя этого значения. Таким образом, строка документации функции eval ссылается на свой первый аргумент как «FORM», потому что фактическое имя аргумента — form:

  Вычислить FORM и вернуть его значение.
  

  Также пишите метасинтаксические переменные заглавными буквами, например, когда вы показываете разложение списка или вектора на части, некоторые из которых могут меняться. «KEY» и «VALUE» в следующем примере иллюстрируют это правило:

  Аргумент TABLE должен быть ассоциативным списком, элементы
  которого имеют вид (KEY . VALUE). Здесь KEY — ...
  

• Никогда не изменяйте регистр символа Lisp, когда упоминаете его в строке документации. Если имя символа — foo, пишите «foo», а не «Foo» (это другой символ).

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

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

• Не начинайте и не заканчивайте строку документации пробелами.
• Не делайте отступы для последующих строк строки документации так, чтобы текст был выровнен в исходном коде по тексту первой строки. Это красиво выглядит в исходном коде, но странно — когда пользователи просматривают документацию. Помните, что отступ перед начальной двойной кавычкой не является частью строки!
• Когда в документации должен отображаться ASCII-апостроф или обратный апостроф, используйте «\\='» или «\\=`» в литерале строки документации, чтобы символ отображался как есть.
• В строках документации не заключайте в кавычки выражения, которые не являются символами Lisp, так как эти выражения могут обозначать сами себя. Например, пишите «Return the list (NAME TYPE RANGE) ...» вместо «Return the list `(NAME TYPE RANGE)' ...» или «Return the list \\='(NAME TYPE RANGE) ...».
• Когда строка документации ссылается на символ Lisp, пишите его так, как он был бы выведен (обычно это означает строчные буквы), с обратным апострофом «`» перед ним и апострофом «'» после него. Есть два исключения: пишите t и nil без окружающих знаков препинания. Например:

  CODE может быть `lambda', nil или t.
  

  Обратите внимание, что когда Emacs отображает эти строки документации, он обычно отображает «`» (обратный апостроф) как «‘» (левая одиночная кавычка) и «'» (апостроф) как «’» (правая одиночная кавычка), если дисплей поддерживает отображение этих символов. См. Подстановка привязок клавиш в документации. (В некоторых предыдущих версиях этого раздела рекомендовалось использовать не-ASCII одиночные кавычки непосредственно в строках документации, но теперь это не рекомендуется, поскольку это приводит к некорректному отображению строк помощи на терминалах, не поддерживающих эти символы.)

  Режим помощи автоматически создаёт гиперссылку, когда строка документации использует имя символа в одиночных кавычках, если этот символ имеет определение функции или переменной. Вам не нужно делать ничего особенного для использования этой возможности. Однако, когда символ имеет и определение функции, и определение переменной, и вы хотите сослаться только на одно из них, вы можете указать, на что именно, написав одно из слов «variable», «option», «function» или «command» непосредственно перед именем символа. (Регистр не имеет значения при распознавании этих слов-индикаторов.) Например, если вы напишете

  Эта функция устанавливает переменную `buffer-file-name'.
  

  то гиперссылка будет вести только на документацию переменной buffer-file-name, а не на документацию функции.

  Если символ имеет определение функции и/или переменной, но они не относятся к использованию символа, которое вы документируете, вы можете написать слова «symbol» или «program» перед именем символа, чтобы предотвратить создание гиперссылки. Например,

  Если аргумент KIND-OF-RESULT является символом `list',
  эта функция возвращает список всех объектов,
  удовлетворяющих критерию.
  

  не создаёт гиперссылку на документацию (здесь не относящуюся к делу) функции list.

  Обычно гиперссылка не создаётся для переменной без документации переменной. Вы можете принудительно создать гиперссылку для таких переменных, предваряя их одним из слов «variable» или «option».

  Гиперссылки для лиц (faces) создаются только в том случае, если имени лица предшествует или за ним следует слово «face». В этом случае будет показана только документация лица, даже если символ также определён как переменная или функция.

  Чтобы создать гиперссылку на документацию Info, напишите имя узла Info (или якоря) в одиночных кавычках, предварив его словами «info node», «Info node», «info anchor» или «Info anchor». Имя файла Info по умолчанию — «emacs». Например,

  См. узел Info `Font Lock' и узел Info `(elisp)Font Lock Basics'.
  

  Чтобы создать гиперссылку на man-страницу, напишите имя man-страницы в одиночных кавычках, предварив его словами «Man page», «man page» или «man page for». Например,

  Подробности см. на man-странице `chmod(1)'.
  

  Документация Info всегда предпочтительнее man-страниц, поэтому обязательно ссылайтесь на руководство Info, если оно доступно. Например, chmod документирован в руководстве GNU Coreutils, поэтому лучше ссылаться на него, а не на man-страницу.

  Чтобы создать ссылку на группу настройки, напишите имя группы в одиночных кавычках, предварив его словами «customization group» (регистр первой буквы в каждом слове не имеет значения). Например,

  Подробности см. в группе настройки `whitespace'.
  

  Наконец, чтобы создать гиперссылку на URL, напишите URL в одиночных кавычках, предварив его словом «URL». Например,

  На веб-сайте проекта GNU есть дополнительная информация (см. URL
  `https://www.gnu.org/').
  

• Не пишите последовательности клавиш непосредственно в строках документации. Вместо этого используйте конструкцию «\\[…]» для их обозначения. Например, вместо написания «C-f» напишите конструкцию «\\[forward-char]». Когда Emacs отображает строку документации, он подставляет ту клавишу, которая в данный момент привязана к forward-char. (Обычно это «C-f», но это может быть другой символ, если пользователь изменил привязки клавиш.) См. Подстановка привязок клавиш в документации.
• В строках документации для основного режима вы, вероятно, захотите ссылаться на привязки клавиш локальной карты этого режима, а не глобальные. Поэтому используйте конструкцию «\\<…>» один раз в строке документации, чтобы указать, какую карту клавиш использовать. Сделайте это перед первым использованием «\\[…]» и не в середине предложения (поскольку если карта не загружена, ссылка на карту будет заменена предложением о том, что карта в данный момент не определена). Текст внутри «\\<…>» должен быть именем переменной, содержащей локальную карту клавиш для основного режима.

  Каждое использование «\\[…]» немного замедляет отображение строки документации. Если вы используете их много, эти небольшие замедления суммируются и могут стать ощутимыми, особенно на медленных системах. Поэтому наша рекомендация — не злоупотреблять ими; например, старайтесь избегать более одной ссылки на одну и ту же команду в одной строке документации.

• Для единообразия формулируйте глагол в первом предложении строки документации функции в повелительном наклонении — например, используйте «Return the cons of A and B.» вместо «Returns the cons of A and B.». Обычно хорошо выглядит делать так же и для остальной части первого абзаца. Последующие абзацы обычно выглядят лучше, если каждое предложение изъявительное и имеет подлежащее.
• Строка документации для функции-предиката «да/нет» должна начинаться со слов типа «Return t if», чтобы явно указывать, что считается истиной. Слово «return» позволяет избежать начала предложения со строчной «t», что могло бы несколько отвлекать.
• Пишите строки документации в действительном залоге, а не в страдательном, и в настоящем времени, а не в будущем. Например, используйте «Return a list containing A and B.» вместо «A list containing A and B will be returned.»
• Избегайте использования слова «cause» (или его эквивалентов) без необходимости. Вместо «Cause Emacs to display text in boldface» пишите просто «Display text in boldface».
• Избегайте использования «iff» (математический термин, означающий «if and only if»), поскольку многие люди с ним не знакомы и принимают его за опечатку. В большинстве случаев смысл ясен и с простым «if». В противном случае постарайтесь найти другую формулировку, передающую смысл.
• Старайтесь по возможности избегать таких сокращений, как «e.g.» (например), «i.e.» (то есть), «no.» (номер), «cf.» (сравните/см. также) и «w.r.t.» (относительно). Почти всегда полная версия понятнее и легче читается.³⁶
• Когда команда имеет смысл только в определённом режиме или ситуации, обязательно упоминайте об этом в строке документации. Например, документация dired-find-file:

  В Dired перейти к файлу или каталогу, указанному в этой строке.
  

• Когда вы определяете переменную, представляющую параметр, который пользователи могут захотеть настроить, используйте defcustom. См. Определение глобальных переменных.
• Строка документации для переменной-флага «да/нет» должна начинаться со слов типа «Non-nil means», чтобы было ясно, что все не-nil значения эквивалентны, и явно указывать, что означают nil и не-nil.
• Если строка в строке документации начинается с открывающей скобки, рассмотрите возможность написания обратной косой черты перед открывающей скобкой, например:

  Аргумент FOO может быть числом
  \(позицией в буфере) или строкой (именем файла).
  

  Это позволяет избежать ошибки в версиях Emacs старше 27.1, где «(» воспринималась как начало определения функции (см. Defuns в Руководстве GNU Emacs). Если вы не ожидаете, что кто-то будет редактировать ваш код в старых версиях Emacs, этот обходной приём не нужен.