Команды go: go doc, показать документацию для пакета или символа

Использование:

go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]

doc печатает комментарии документации, связанные с элементом, идентифицированным его аргументами (поле package, const, func, type, var, method или struct), за которым следует однострочная сводка каждого из элементов первого уровня "под" этим элементом (объявления уровня пакета для пакета, методы для типа и т. д.).

doc принимает ноль, один или два аргумента.

При отсутствии аргументов, то есть когда запускается как

go doc

он печатает документацию пакета для пакета в текущем каталоге. Если пакет является командой (основной пакет), экспортированные символы пакета удаляются из представления, если не указан флаг -cmd.

При запуске с одним аргументом аргумент обрабатывается как Go-синтаксическое представление элемента, подлежащего документированию. То, что выбирает аргумент, зависит от того, что установлено в GOROOT и GOPATH, а также от формы аргумента, которая схематически является одной из них:

go doc <pkg>
go doc <sym>[.<methodOrField>]
go doc [<pkg>.]<sym>[.<methodOrField>]
go doc [<pkg>.][<sym>.]<methodOrField>

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

Для пакетов порядок сканирования определяется лексически в порядке убывания. Таким образом, представленный пакет является тем, который соответствует поиску и является ближайшим к корню и лексически первым на его уровне иерархии. Дерево GOROOT всегда сканируется полностью перед GOPATH.

Если пакет не указан или не найден, пакет в текущем каталоге выбирается, поэтому "go doc Foo" показывает документацию для символа Foo в текущем пакете.

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

При запуске с двумя аргументами, первый должен быть полным путем пакета (а не просто суффиксом), а второй - символом или символом с методом или структурным полем. Это похоже на синтаксис, принятый godoc:

go doc <pkg> <sym>[.<methodOrField>]

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

Примеры:

go doc
    Показать документацию для текущего пакета.
go doc Foo
    Показать документацию для Foo в текущем пакете.
    (Foo начинается с заглавной буквы, 
    поэтому не может соотвествовать пути пакета.)
go doc encoding/json
    Показать документацию для encoding/json пакета.
go doc json
    Сокращение для encoding/json.
go doc json.Number (или go doc json.number)
    Показать документацию и краткое описание метода для json.Number.
go doc json.Number.Int64 (или go doc json.number.int64)
    Показать документацию для json.Number Int64 метода.
go doc cmd/doc
    Показать пакет документов для команды doc.
go doc -cmd cmd/doc
    Показать документы пакета и экспортированные символы в команде doc.
go doc template.new
    Показать документацию для функции New в html/template.
    (html/template лексически идет до text/template)
go doc text/template.new # Один аргумент
    Показать документацию для функции New в text/template.
go doc text/template new # Два аргумента
    Показать документацию для функции New в text/template.

По крайней мере, в текущем дереве все эти вызовы выводят
документация для метода декодирования json.Decoder:

go doc json.Decoder.Decode
go doc json.decoder.decode
go doc json.decode
cd go/src/encoding/json; go doc decode

Флаги:

-all
    Показать всю документацию для пакета.
-c
    Учитывать регистр при сопоставлении символов.
-cmd
    Рассматривайте команду (основной пакет, пакет main) как для обычного пакета.
    В противном случае экспортируемые символы пакета main будут скрыты
    при показе документации верхнего уровня пакета.
-src
    Показать полный исходный код символа. Это будет
    отображать полный исходный код Go своей декларации и
    определение, такое как определение функции (включая
    тело), объявление типа или вложенный const
    блок. Поэтому выходные данные могут включать в себя неэкспортированные
    подробности.
-u
    Показать документацию для неэкспортированных, а также экспортированных
    символов, методов и полей.

---

Читайте также:

• Команды Go: введение
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей