<code>// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {
  </code>

Комментарии к объявлениям пакетов должны содержать общее описание пакета. Эти комментарии могут быть короткими, как краткое описание пакета sort:

<code>// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
</code>

Они также могут быть подробными, как обзор пакета gob. Этот пакет использует другую конвенцию для пакетов, которым требуется большое количество вводной документации: комментарий к пакету размещается в отдельном файле, doc.go, который содержит только эти комментарии и объявление пакета.

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

Комментарии, которые не примыкают к объявлению уровня пакета, исключаются из вывода godoc, с одним замечательным исключением. Комментарии уровня пакета, начинающиеся со слова "BUG(кто)”, распознаются как известные ошибки, и включаются в раздел «Bugs» документации пакета. Часть «кто» должна быть именем пользователя, который может предоставить дополнительную информацию. Например, это известная проблема из пакета bytes:

<code>// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
</code>

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

Существует несколько правил форматирования, которые Godoc использует при преобразовании комментариев в HTML:

• Последующие строки текста считаются частью одного абзаца; необходимо оставить пустую строку для разделения абзацев.

• Текст с предварительным форматированием должен быть отступлен относительно окружающего текста комментариев (см. пример в doc.go пакета gob).

• URL-адреса будут преобразованы в HTML-ссылки; специальная разметка не требуется.

Обратите внимание, что ни одно из этих правил не требует от вас делать что-либо необычное.

На самом деле, лучшее в минимальном подходе godoc — это то, насколько просто его использовать. В результате большинство кода на Go, включая всю стандартную библиотеку, уже соответствует этим соглашениям.

Ваш собственный код может предоставлять хорошую документацию просто благодаря наличию комментариев, описанных выше. Любые пакеты Go, установленные внутри $GOROOT/src/pkg и любые рабочие пространства GOPATH уже будут доступны через командную строку и HTTP-интерфейсы godoc, и вы можете указать дополнительные пути для индексации с помощью флага -path или просто выполнив команду "godoc ." в каталоге исходного кода. См. документацию godoc для получения дополнительных сведений.