Команда godoc в Golang

godoc извлекает и генерирует документацию для программ Go.

Он работает как веб-сервер и представляет документацию как веб-страницу.

godoc -http=:6060

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

godoc [flag]

Флаги:

-v
    режим с подробным выводом

-timestamps=true
    показать временные метки (timestamps) 
    со списком каталогов

-index
    включить идентификатор и индекс 
    полнотекстового поиска (окно поиска не отображается, 
    если -index не установлен)

-index_files=""
    шаблон glob с указанием индексных файлов; 
    если не пустой, индекс читается из этих файлов 
    в отсортированном порядке

-index_throttle=0.75
    значение указателя дроссельной заслонки; 
    значение 0 означает, что время не выделяется
    для индексатора (индексатор никогда не завершится), 
    значение 1,0 означает, что создание индекса 
    выполняется с полной скоростью (другим goroutines 
    может не хватить времени, пока индекс строится)

-index_interval=0
    интервал индексации; значение 0 устанавливает 5 минут,
    отрицательные значения индексов - 
    только один раз при запуске

-play=false
    включить песочницу

-links=true
    связать идентификаторы с их объявлениями

-write_index=false
    записать индекс в файл; 
    имя файла должно быть указано с
    -index_files

-maxresults=10000
    показано максимальное количество результатов 
    полнотекстового поиска (полнотекстовый индекс 
    не создается, если maxresults <= 0)

-notes="BUG"
    маркеры соответствия регулярного выражения, 
    чтобы показать (например, "BUG|TODO", ".*")

-goroot=$GOROOT
    Go корневой каталог

-http=addr
    адрес HTTP сервиса 
    (например, '127.0.0.1:6060' или просто ':6060')

-analysis=type,pointer
    разделенный запятыми список анализов для выполнения
    "type": отображать разрешение идентификатора, 
            информацию о типе, наборы методов,
            'implements' и статические вызываемые
    "pointer": отображать одноранговые каналы, 
               вызывающие и динамические абоненты канала
               (значительно медленнее)

-templates=""
    каталог, содержащий альтернативные файлы шаблонов;
    если установлено, каталог может содержать 
    альтернативные файлы шаблонов
    для файлов в $GOROOT/lib/godoc

-url=path
    вывести на стандартный вывод данные, 
    которые будут выдаваться
    HTTP запросом для указанного пути (path)

-zip=""
    zip-файл, предоставляющий файловую систему 
    для обслуживания; отключено, если пусто

По умолчанию godoc просматривает пакеты, которые находит через $GOROOT и $GOPATH (если установлены). Это поведение можно изменить, указав альтернативный $GOROOT с флагом -goroot.

Когда установлен флаг -index, индекс поиска сохраняется. Индекс создается при запуске.

Индекс содержит информацию как по идентификатору, так и по полнотекстовому поиску (поиск по регулярным выражениям) Максимальное количество отображаемых результатов полнотекстового поиска можно установить с помощью флага -maxresults; если установлено значение 0, полнотекстовые результаты не отображаются, и создается только индекс идентификатора, но не создается индекс полнотекстового поиска.

По умолчанию godoc использует системные GOOS/GOARCH. Вы можете указать параметры URL "GOOS" и "GOARCH", чтобы настроить вывод на веб-странице целевой системы.

Режим представления веб-страниц, обслуживаемых godoc, можно контролировать с помощью URL параметра "m"; в качестве значения он принимает список имен флагов через запятую:

all     показывать документацию для всех объявлений, 
        а не только экспортируемых

methods показывать все встроенные методы, а не только те, 
        которые не были экспортированы анонимными полями

src     показывать исходный код, 
        а не извлеченную документацию

flat    представить плоский (без отступа) 
        список каталогов с использованием полных путей

Например, https://golang.org/pkg/math/big/?m=all показывает документацию для всех (не только экспортируемых) объявлений пакета big.

По умолчанию godoc обслуживает файлы из файловой системы базовой ОС. Вместо этого .zip-файл может быть предоставлен с помощью флага -zip, который содержит файловую систему для обслуживания. Пути к файлам, хранящиеся в .zip-файле, должны использовать косую черту ('/') в качестве разделителя пути; и они должны быть без корней. Для $GOROOT (или -goroot) должен быть указан путь к каталогу файла .zip, содержащий корневой каталог Go. Например, для файла .zip, созданного командой:

zip -r go.zip $HOME/go

можно запустить godoc следующим образом:

godoc -http=:6060 -zip=go.zip -goroot=$HOME/go

Документация godoc конвертируется в HTML или в текст с использованием пакета go/doc. Godoc также показывает пример кода, который запускается пакетом тестирования

---

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

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

Команды 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, компиляция пакетов и зависимостей