Автоматически генерируйте полезную документацию для ваших проектов Go из комментариев к коду
Когда вы думаете о программировании, естественно сосредоточиться на таких темах, как языки, алгоритмы и отладка. Но техническая документация может быть не менее важна
Без хорошей документации может пострадать возможность повторного использования кода. Если документация не соответствует требованиям, пользователи, только что познакомившиеся с кодовой базой, могут легко потеряться или разочароваться. Важно не только понимать, что делает программа, но и как— или даже почему— она это делает
Такие пакеты, как Pydoc для Python и Javadoc для Java, помогают автоматизировать часть процесса. Инструмент Godoc делает то же самое для Go
Что такое Godoc?
Godoc – это пакет для Go, который позволяет создавать, управлять и использовать документацию Go “способом Go . Путь Go – это набор принципов, которым вы, как Go-программист, должны следовать для улучшения качества кода
Используя Godoc, вы можете легко читать документацию и код других разработчиков. Вы также можете автоматизировать создание собственной документации и опубликовать ее с помощью Godoc
Godoc похож на Javadoc, документатор кода для Java. Они оба используют комментарии и код в модулях для создания документации. И оба инструмента структурируют эту документацию в HTML, чтобы вы могли просматривать ее в браузере
Начало работы с Godoc
Использовать Godoc очень просто. Для начала установите пакет Godoc с сайта golang с помощью этой команды:
goget golang.org/x/tools/cmd/godoc
Выполнение этой команды приведет к установке Godoc в указанное вами рабочее пространство. После ее завершения вы сможете выполнить команду godoc в терминале. Если при установке возникли ошибки, попробуйте обновить Go до последней версии
Как комментировать свой код
Godoc ищет однострочные и многострочные комментарии для включения в создаваемую документацию
Для достижения наилучших результатов обязательно форматируйте код в стиле Go, как описано в публикации Effective Go, подготовленной командой Go
Вот пример, использующий однострочные комментарии в стиле C++:
// User is a struct model containing
typeUserstruct
Вы также можете использовать блочные комментарии в стиле C:
/*
User is a custom data structure
You can include any text here and the Godoc server will format it when you run it.
*/
typeUserstruct
В приведенных выше комментариях “Пользователь начинает предложения, потому что комментарий описывает то, что делает структура User. Это одна из многих тем, которые обсуждаются в Go way. Начинать предложения документации с полезного имени крайне важно, поскольку первое предложение появляется в списке пакетов
Запуск сервера Godoc
После того как вы закомментировали свой код, вы можете запустить команду godoc в терминале из каталога кода вашего проекта
Обычно разработчики Go используют порт 6060 для размещения документации. Это команда для запуска сервера Godoc на этом порту:
godoc -http=:6060
Приведенная выше команда размещает вашу документацию по коду на localhost, или 127. 0. 0. 1. Порт не обязательно должен быть 6060; godoc будет работать на любом незанятом порту. Однако всегда лучше следовать соглашениям документации Go
После выполнения команды вы можете просмотреть документацию в браузере по адресу localhost:6060. Время, которое потребуется Godoc для создания вашей документации, будет зависеть от ее размера и сложности
Пример программы с комментариями Godoc
Приведенный ниже код придерживается пути Go, в данном случае используя однострочные комментарии
// name of the package
packageuser
// fmt is responsible for formatting
import
'fmt'
// User is a struct of human data
typeUserstruct
Ageint
Namestring
funcmain()
// human is an initialization of the User struct
human := User {
Age:
Name:'person'
}
fmt.Println(human.Talk()).
// Talk is a method of the User struct
func(receiver User)Talk()string
return'Every User Gets to Say Something!'
Если вы запустите Godoc на приведенном выше модуле кода, вы должны увидеть результат, выглядящий примерно так:
Обратите внимание, что он имеет привычный формат, похожий на тот, что вы найдете на сайте официальной документации Go
Godoc использует комментарий, предшествующий объявлению пакета, как Обзор. Убедитесь, что этот комментарий описывает то, что делает ваша программа
Индекс Index содержит ссылки на объявления типов и методов, чтобы вы могли быстро перейти к ним
Godoc также предоставляет функциональность для просмотра исходного кода, составляющего пакет, в разделе Package files
Улучшение документации с помощью Godoc
Вы можете включать в документацию Godoc не только обычный текст. Вы можете добавлять URL, для которых Godoc будет генерировать ссылки, и структурировать ваши комментарии в параграфы
Если вы хотите сделать ссылку на ресурс, напишите URL в комментарии, и Godoc распознает его и добавит ссылку. Для абзацев оставьте пустую строку комментария
// Package main
packagemain
// Document represents a regular document.
//
// Link to https://google.com
typeDocumentstruct
pagesint
referencesstring
signedbool
// Write writes a new Document to the storage
//
// You can learn about writing from Wikipedia.com
funcWrite()
Обратите внимание, что Godoc требует полного написания URL-адресов, чтобы он мог их связать. В этом примере URL Google включает префикс https:// , поэтому Godoc добавляет ссылку на него. Поскольку домен Википедии сам по себе не является полным URL, Godoc оставит его в покое
Вот несколько лучших принципов, которые следует применять при документировании кода Go:
- Сохраняйте документацию простой и лаконичной.
- Начинайте предложения функций, типов и объявления переменных с их имен.
- Начните строку с отступа, чтобы предварительно отформатировать ее как код.
- Комментарии, начинающиеся с ‘BUG(name)’, например ‘BUG(joe): This doesn’t work’ являются особенными.Godoc будет распознавать их как ошибки и сообщать о них в отдельном разделе документации.
Godoc может облегчить ваши проблемы с документацией
Используя Godoc, вы можете быть более продуктивными и меньше беспокоиться о том, что вам придется документировать свои программы вручную
Чтобы целевой аудитории было легче читать и понимать вашу документацию, она должна быть точной, подробной и понятной. Также очень важно, чтобы комментарии к коду обновлялись по мере изменения программы
Ознакомьтесь с документацией пакета Godoc, чтобы узнать больше об использовании Godoc
Комментировать