Go предоставляет блочные комментарии /* */ в стиле C и строковые комментарии // в C++ стиле. Строковые комментарии являются нормой; блочные комментарии появляются в основном как комментарии пакета, но полезны в выражении или для отключения больших участков кода.
Программа (и веб-сервер) godoc обрабатывают файлы с исходным Go кодом, чтобы извлечь документацию о содержании пакета. Комментарии, которые появляются перед объявлениями верхнего уровня, без промежуточных строк, извлекаются вместе с декларацией, и служат пояснительным текстом для предмета. Характер и стиль этих комментариев определяет качество документации производимой godoc.
Каждый пакет должен иметь пакетный комментарий, блок комментариев перед началом скобок пакета. Для многофайловых пакетов комментарий пакета должен присутствовать только в одном файле. Комментарий пакета должен представить пакет и предоставить информацию, относящуюся к пакету в целом. Он появится первым на странице godoc и следует настроить подробную документацию образом аналогичным следующему примеру.
/*
Package regexp implements
a simple library for regular expressions.
The syntax of the regular expressions accepted is:
regexp:
concatenation { '|' concatenation }
concatenation:
{ closure }
closure:
term [ '*' | '+' | '?' ]
term:
'^'
'$'
'.'
character
'[' [ '^' ] character-ranges ']'
'(' regexp ')'
*/
package regexp
/*
Пакет regexp является
простой библиотекой для регулярных выражений.
Синтакс регулярных выражений принимаемый пакетом:
regexp:
concatenation { '|' concatenation }
concatenation:
{ closure }
closure:
term [ '*' | '+' | '?' ]
term:
'^'
'$'
'.'
character
'[' [ '^' ] character-ranges ']'
'(' regexp ')'
*/
package regexp
Если пакет простой, комментарий пакета может быть кратким.
// Пакет path реализует служебные процедуры для
// манипулирования разделенными слешем путями к файлам.
Комментарии не нуждаются в дополнительном форматировании. Сгенерированный вывод может даже не быть представлен шрифтом фиксированной ширины, поэтому не зависит от интервала для выравнивания - godoc, как и gofmt, позаботится об этом. Комментарии представляют собой неинтерпретируемый текст, поэтому HTML и другие аннотации, такие как _this_, воспроизводятся дословно и не должны быть использованы. Выравнивание выполняемое godoc, заключается в отображении расположенного с отступом текста шрифтом фиксированной ширины, подходящем для фрагментов программы. Комментарий пакета для fmt пакета использует это для лучшего эффекта.
В зависимости от контекста, godoc может даже не переформатировать комментарии, поэтому убедитесь, что они выглядят хорошо: используйте правильное написание, пунктуацию и структуру предложения, переносите длинные строки и так далее.
Внутри пакета любой комментарий, непосредственно предшествующий объявлению верхнего уровня служит комментарием документа для этой декларации. Каждое экспортированное (заглавное) имя в программе должно иметь комментарий документа.
Комментарии в документации лучше всего работают как полные предложения, которые позволяют использовать широкий спектр автоматизированных презентаций. Первое предложение должно состоять из одного предложения-резюме, которое начинается с объявляемого имени.
// Compile анализирует регулярное выражение и возвращает,
// в случае успеха, Regexp (регулярное выражение),
// которое можно использовать для сопоставления с текстом.
func Compile (str string) (*Regexp, error) {
Если каждый комментарий документа начинается с названия элемента, который он описывает, вывод godoc может быть удобно запущен с помощью grep. Представьте, что вы не можете вспомнить название "Compile", но искали функцию синтаксического анализа для регулярных выражений, поэтому вы запустили команду:
$ godoc regexp | grep -i parse
Если все комментарии к документу в пакете начинались, «This function...», grep не поможет вам вспомнить имя. Но поскольку пакет начинает каждый комментарий с имени, вы увидите что-то вроде следующего, что напоминает слово, которое вы ищете.
$ godoc regexp | grep parse
Compile parses a regular expression
and returns, if successful, a Regexp parsed.
It simplifies safe initialization of global
variables holding cannot be parsed. It simplifies
safe initialization of global variables
$
Синтаксис объявлений Go позволяет группировать объявления. Один комментарий к документу может вводить группу связанных констант или переменных. Поскольку вся декларация представлена, такой комментарий часто может быть небрежным.
// Коды ошибок, возвращаемых неудачами в анализе выражения.
var (
ErrInternal = errors.New("regexp: internal error")
ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
...
)
Группировка может также указывать отношения между элементами, например, тот факт, что набор переменных защищен мьютексом.
var (
countLock sync.Mutex
inputCount uint32
outputCount uint32
errorCount uint32
)
Читайте также:
Комментариев нет:
Отправить комментарий