Структура

Как документировать несколько похожих процедур

Избегайте написания документации процедуры в форме:

«Как [другой метод], за исключением...»

даже если они находятся в одном классе, потому что читатели могут не читать всю страницу класса, а скорее перейти к конкретной процедуре (возможно, даже вне контекста в разделе /routine/ веб-сайта) и ожидать, что она расскажет им, как это работает, без необходимости искать информацию по всему сайту.

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

Ссылки на документы

Старайтесь избегать абсолютных URL-адресов.

L<foo|/routine/foo>

Работает хорошо.

Если вам нужно использовать полный URL-адрес в документах или где-либо ещё, убедитесь, что поддомен — «docs», а протокол — «https://» (например, https://docs.perl6.org/blah/blah). Другие варианты URL-адреса всё равно будут работать для удобства, но все они просто перенаправляют на каноническую версию, поэтому лучше всего использовать её с самого начала.

Язык

«say» против «put»

Хотя нет жёсткого правила о том, какую из этих процедур использовать в данной ситуации, пожалуйста, постарайтесь следовать этим рекомендациям.

При генерации вывода в примерах, предназначенных для чтения пользователем, используйте «say». Кроме того, добавьте комментарий, показывающий предполагаемый вывод, например:

say 3.^name; #OUTPUT: «Int␤»

Для примеров, где требуется определённый формат или ожидаются точные данные (например, для чего-то, отправленного через сетевое соединение), предпочитайте «put».

«параметр» против «аргумент»

• Аргумент: то, как он выглядит для вызывающего.
• Параметр: то, как он выглядит для функции.

S06: «В культуре Perl 6 мы различаем термины параметр и аргумент; параметр — это формальное имя, которое будет привязано к входящему аргументу во время выполнения, в то время как аргумент — это фактическое значение, которое будет связано с формальным параметром. Процесс прикрепления этих значений (аргументов) к их временным именам (параметрам) известен как связывание. (В некоторой литературе по CS используются термины «формальный аргумент» и «фактический аргумент» для этих двух понятий, но здесь мы стараемся избегать использования термина «аргумент» для формальных параметров.)»

«объект» против «значение»

Вы можете использовать объект для всего, к чему вы можете вызывать методы, включая объекты значений и объекты типов. Рассмотрите экземпляр для определённых объектов.

Используйте настоящее время, когда говорите о функциях Perl 5

Perl 5 всё ещё является активным языком, поэтому вместо «В Perl 5 это использовалось для..., но в Perl 6...» используйте форму «В Perl 5 это используется для..., но в Perl 6...».

Не упоминайте Perl 5, если только это не документ 5–6 или связанный документ

Мы не ожидаем, что нашим пользователям придётся знать Perl 5, чтобы изучить Perl 6, так что это не должно быть частью основной документации.

Используйте неразрывные пробелы при работе с номерами версий Perl

Чтобы номер версии не переносился на отдельную строку от термина «Perl», используйте неразрывный пробел (NBSP), который кодируется как символ Unicode U+00A0.

Чтобы преобразовать все имена Perl в этом стиле в SOME-FILE, вы можете использовать этот однострочный код:

perl -C -pi -e 's/Perl (6|5)/Perl\x{A0}$1/g' SOME-FILE

Область применения

Что следует документировать? Основная цель программной документации — охватить элементы, которые являются частью спецификации (набор тестов roast).

• Если что-то видно пользователям Perl 6 и находится в roast: документируйте это.
• Если что-то видимо пользователям Perl 6 и не находится в roast: проконсультируйтесь с командой разработчиков (#perl6-dev на freenode) — возможно, потребуется добавить тест (и, следовательно, документы), или его необходимо скрыть, чтобы пользователи не могли его увидеть.

Будущие соображения по этому вопросу включают: документирование вещей, специфичных для rakudo (таких как «dd»), и документирование доступных версий элементов спецификации.