The Go Blog

Godoc: documenting Go code

Andrew Gerrand
31 March 2011

The Go project takes documentation seriously. Documentation is a huge part of making software accessible and maintainable. Of course it must be well-written and accurate, but it also must be easy to write and to maintain. Ideally, it should be coupled to the code itself so the documentation evolves along with the code. The easier it is for programmers to produce good documentation, the better for everyone.

To that end, we have developed the godoc documentation tool. This article describes godoc’s approach to documentation, and explains how you can use our conventions and tools to write good documentation for your own projects.

Godoc parses Go source code — including comments — and produces documentation as HTML or plain text. The end result is documentation tightly coupled with the code it documents. For example, through godoc’s web interface you can navigate from a function’s documentation to its implementation with one click.

Godoc is conceptually related to Python’s Docstring and Java’s Javadoc but its design is simpler. The comments read by godoc are not language constructs (as with Docstring) nor must they have their own machine-readable syntax (as with Javadoc). Godoc comments are just good comments, the sort you would want to read even if godoc didn’t exist.

The convention is simple: to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line. Godoc will then present that comment as text alongside the item it documents. For example, this is the documentation for the fmt package’s Fprint function:

Notice this comment is a complete sentence that begins with the name of the element it describes. This important convention allows us to generate documentation in a variety of formats, from plain text to HTML to UNIX man pages, and makes it read better when tools truncate it for brevity, such as when they extract the first line or sentence.

Comments on package declarations should provide general package documentation. These comments can be short, like the sort package’s brief description:

They can also be detailed like the gob package’s overview. That package uses another convention for packages that need large amounts of introductory documentation: the package comment is placed in its own file, doc.go, which contains only those comments and a package clause.

When writing package comments of any size, keep in mind that their first sentence will appear in godoc’s package list.

Comments that are not adjacent to a top-level declaration are omitted from godoc’s output, with one notable exception. Top-level comments that begin with the word «BUG(who)” are recognized as known bugs, and included in the «Bugs” section of the package documentation. The «who” part should be the user name of someone who could provide more information. For example, this is a known issue from the bytes package:

Sometimes a struct field, function, type, or even a whole package becomes redundant or unnecessary, but must be kept for compatibility with existing programs. To signal that an identifier should not be used, add a paragraph to its doc comment that begins with «Deprecated:» followed by some information about the deprecation.

There are a few formatting rules that Godoc uses when converting comments to HTML:

Subsequent lines of text are considered part of the same paragraph; you must leave a blank line to separate paragraphs.

Pre-formatted text must be indented relative to the surrounding comment text (see gob’s doc.go for an example).

URLs will be converted to HTML links; no special markup is necessary.

Note that none of these rules requires you to do anything out of the ordinary.

In fact, the best thing about godoc’s minimal approach is how easy it is to use. As a result, a lot of Go code, including all of the standard library, already follows the conventions.

Your own code can present good documentation just by having comments as described above. Any Go packages installed inside $GOROOT/src/pkg and any GOPATH work spaces will already be accessible via godoc’s command-line and HTTP interfaces, and you can specify additional paths for indexing via the -path flag or just by running «godoc .» in the source directory. See the godoc documentation for more details.

Как установить и настроить Go на Windows

Go является простым языком программирования общего назначения, которого будет не лишним добавить в вашу коллекцию изученных языков. Проект стартовал в 2007 году, и благодаря усилиям разработчиков Google, стал тем языком Go, с которым мы можем работать сегодня. Внимание уделялось легкости и согласованности языка, его инструментов и стандартных библиотек, делая Go простым и занятным в использовании.

Содержание статьи

У Go открытый исходный код, что здорово. И не забывайте — данный язык чувствителен к регистру.

Рекомендуем вам супер TELEGRAM канал по Golang где собраны все материалы для качественного изучения языка. Удивите всех своими знаниями на собеседовании! 😎

Мы публикуем в паблике ВК и Telegram качественные обучающие материалы для быстрого изучения Go. Подпишитесь на нас в ВК и в Telegram. Поддержите сообщество Go программистов.

Разберем процесс установки Go на Windows 10. Вы увидите, как это просто — достаточно базовых знаний о GitHub и работы с командной строкой. Конечно, это не единственный способ установки, однако он будет наиболее простым для тех, чьи знания кодирования ограничены. Просто придерживайтесь данных инструкций.

Следуйте указаниям, придерживаясь правильного порядка, чтобы потом не мучиться и не исправлять ошибки, возникшие во время процесса инсталляции.

Установка элементов в правильном порядке

1. Так как зачастую Go использует бесплатные репозитории с открытым исходным кодом, сначала установить пакет Git, перейдя по ссылке;
2. Перейдите на сайт инсталляции Go по ссылке. Скачайте и установите последний 64-битный набор Go для Microsoft Windows OS;
3. Следуйте инструкциям по установке программы Go;
4. Откройте командную строку cmd и наберите go version ;
5. Вывод после ввода go version должен выглядеть следующим образом (в зависимости от версии, она может быть у вас другая):

Создание рабочего пространства Go

Для начала подтвердим работоспособность Go. Откройте Панель Управления, затем следуйте в Система и безопасность > Система > Дополнительные параметры системы. Кликните на Переменные Среды с правой нижней стороны. Убедитесь, что у Path в Системные Переменные есть значение C:\Go\bin .

Затем нужно создать рабочее пространство Go. Оно будет в отдельной новой папке от той, где сохранены и установлены файлы Go. К примеру, ваши установленные файлы Go могут находиться по пути C:\Go , а создать рабочее пространство Go можно по адресу C:\Projects\Go .

В новой папке рабочего пространства Go настраиваем три новые папки — bin , pkg , src :

Создание переменной среды GOPATH

Создадим переменную GOPATH и свяжем ее с недавно созданным рабочим пространством Go. Перейдите обратно в Панель Управления, затем в Система и потом на Переменные среды. Затем под Системные Переменные нажмите на Создать.

Рядом с Имя переменной введите GOPATH, а рядом с Значение переменной введите C:\Projects\Go:

Проверить, установлены ли пути верно можно через ввод echo %GOPATH% в командной строке.

Тестирование установки Golang в Windows

Теперь можно проверить, действительно ли все работает правильно. Откройте командную строку и наберите: go get github.com/golang/example/hello .

Подождите, когда код будет полностью скомпилировано (на это уйдет пару секунд), затем наберите следующую команду: %GOPATH%/bin/hello .

Если установка была успешной, вы должны получить следующее сообщение: “Hello, Go examples!”

Надеюсь, у вас все получилось. Если же возникли какие-то ошибки или появились непонятные сообщения, наберите внизу результат командной строки: “go env” .

При составлении данной статьи использовались указанные ниже ресурсы, которые также могут помочь при настройке Go на операционной системе Windows: Wade Wegner’s visually-simple & stylistic article.

Администрирую данный сайт с целью распространения как можно большего объема обучающего материала для языка программирования Go. В IT с 2008 года, с тех пор изучаю и применяю интересующие меня технологии. Проявляю огромный интерес к машинному обучению и анализу данных.

E-mail: vasile.buldumac@ati.utm.md

Образование

Технический Университет Молдовы (utm.md), Факультет Вычислительной Техники, Информатики и Микроэлектроники

• 2014 — 2018 Universitatea Tehnică a Moldovei, ИТ-Инженер. Тема дипломной работы «Автоматизация покупки и продажи криптовалюты используя технический анализ»
• 2018 — 2020 Universitatea Tehnică a Moldovei, Магистр, Магистерская диссертация «Идентификация человека в киберпространстве по фотографии лица»

Godoc golang как пользоваться windows

1687 просмотра

2 ответа

Я боролся с godoc и обнаружил, что «go doc» больше подходит для предоставления помощи по использованию из командной строки, например:

перечисляет комментарий пакета и любые функции (или другие объекты)

затем показывает документацию для отдельной функции (или другого объекта)

Кажется, есть связанный инструмент, называемый godoc . Godoc также, похоже, генерирует HTML для каждого пакета и функции. Например

Создает HTML, содержащий комментарий пакета только для stdout

Годок — действительно запутанное имя, учитывая, что у нас также есть документация !

Как я могу создать статическую документацию для всего проекта?

Это похоже на Godoc, создайте html для всего пакета, который может быть неверно истолкован как запрос документации о пакетах, а не проектах. Мне нужен шаг сборки, который я могу использовать в проекте, который в принципе может содержать много пакетов и приложений.

Ответы (2)

0 плюса

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

1. убедитесь, что у вас установлен «wget» (я использую Mac, поэтому пришлось установить его с помощью X-кода)
2. Войдите в систему как пользователь root и измените файл с именем «robots.txt», чтобы удалить строку «Disallow: /», поскольку это не позволяет wget рекурсивно загружать сайт. Файл «robots.txt» должен находиться в пути $ GOROOT.

откройте cmd и запустите сервер godocs, используя команду ниже

godoc -http =: 6060

У меня настроен локальный путь к этому порту. 4. Откройте другой cmd и выполните приведенную ниже команду.

Вы можете указать путь к проекту для загрузки html-документации для всего проекта.

Автор: braj Размещён: 09.01.2019 10:46

0 плюса

Есть ли канонический способ создания документации для автономного использования, даже с использованием Godoc?

godoc а также go doc

В Go 1.12 godoc больше нет интерфейса командной строки, а только веб-сервер.
Пользователи должны использовать go doc для вывода справки из командной строки.

go doc теперь поддерживает -all флаг , который заставит его печатать все экспортированные API и их документацию, как godoc раньше делала командная строка.

cmd/doc : добавьте -all флаг, чтобы распечатать всю документацию для пакета

В отличие от старого godoc , вам нужен -u флаг, чтобы увидеть неэкспортированные символы.
Это похоже на правильное поведение: оно соответствует.

GoDoc not found #231

Comments

pyros2097 commented Mar 8, 2016

I’m using go 1.6 and I get this error whenever I hover over a type The «godoc» command is not available.
Is there some way to stop this since you can get the doc using «go doc» command now.
Trying to get it using this
go get -d golang.org/x/tools/cmd/godoc
I get this error
go install golang.org/x/tools/cmd/godoc: open /usr/lib/go/bin/godoc: permission denied

And also shouldn’t getting this tool be in the readme

The text was updated successfully, but these errors were encountered:

Gaboose commented Apr 1, 2016 •

EDIT: this most likely won’t produce correct behaviour in vs code, as @lukehoban noted

I get the same thing. My temporary fix is to put an executable «godoc» text file in $GOPATH/bin with this inside:

Tried to do this with an alias first, but vscode couldn’t see it.

lukehoban commented Apr 4, 2016

Sounds like godoc installs to your $GOROOT/bin instead of $GOPATH . There’s some notes on this here: http://stackoverflow.com/questions/33752247/unable-to-install-go-packages.

Not sure what else vscode-go can do in this case — other than find a way to provide this support without using godoc . In another issue, it was suggested to use https://github.com/zmb3/gogetdoc instead, but that currently only support Go 1.6, which may not work for a decent portion of users.

Note that godoc and go doc do not do the same thing, so @Gaboose’s suggestion most likely won’t produce correct behaviour in VS Code.

pyros2097 commented Apr 5, 2016

I was wondering whether they functioned the same. Anyway thanks for the stackoverflow link got godoc installed.

lukehoban commented Apr 14, 2016

Going to close this out now — since I can’t think of anything more vscode-go can do — other than what’s tracked in #87.

NikosEfthias commented Aug 19, 2016

same problem here and no idea how to fix . Icant understand how this issue was closed without a solution ?