Что такое godoc и как с его помощью документировать код?

Question

Что такое godoc и как с его помощью документировать код?

Тип вопроса: Командные практики Вероятность: 10% Категория: Golang Разработчик

Ответ

godoc — это стандартный инструмент из набора утилит Go, который анализирует исходный код и генерирует из комментариев документацию.

Это ключевой элемент философии Go, поощряющей написание самодокументируемого кода. Весь официальный сайт документации pkg.go.dev построен на этом принципе.

Как это работает:

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

Пример документирования функции:

// Add складывает два целых числа и возвращает их сумму.
//
// Эта функция является простой демонстрацией того, как godoc
// обрабатывает комментарии для создания документации.
func Add(a, b int) int {
    return a + b
}

Как использовать godoc:

Через командную строку: Для быстрого просмотра документации прямо в терминале.

# Показать документацию для функции Println из пакета fmt
go doc fmt.Println

# Показать документацию для всего пакета http
go doc net/http

Запуск локального сервера документации: Для просмотра документации в браузере, аналогично pkg.go.dev.
```
# Запустит сервер на порту 6060
godoc -http=:6060
```
После этого можно открыть в браузере http://localhost:6060/pkg/ и навигироваться по документации ваших локальных проектов и стандартной библиотеки.

Отличие от Swagger/OpenAPI:

godoc предназначен для документирования кода (пакетов, функций, типов) для других разработчиков.
Swagger/OpenAPI предназначен для документирования HTTP API для клиентов этого API.

Ответ 18+ 🔞

Ну, слушай, вот есть у нас в Го такая штука — godoc. Это, блядь, не просто какая-то утилита, это, сука, целая философия! Сидит она в коробке с инструментами и высасывает из твоих комментариев документацию. Весь официальный сайт pkg.go.dev — это, по сути, её рук дело, ёпта.

Как эта мартышка работает?

Она, хитрая жопа, выискивает в коде комментарии, которые ты написал прямо перед объявлением чего угодно — пакета, функции, типа — и делает из них красивую документацию. Без лишних телодвижений, в рот меня чих-пых!

Вот, смотри, как надо:

// Add складывает два целых числа и возвращает их сумму.
//
// Эта функция — простая демонстрация того, как godoc
// превращает твои потуги в комментариях в нечто читаемое.
func Add(a, b int) int {
    return a + b
}

Как этим пользоваться, чтобы не выглядеть идиотом?

Через терминал, по-быстрому. Захотел узнать, что делает Println — не лезь в интернет, спроси у go doc!

# Спросим у бога документации про fmt.Println
go doc fmt.Println

# А теперь про весь пакет net/http, чтоб знать, с чем имеем дело
go doc net/http

Запустить локальный сервак, чтоб всё было красиво. Это когда тебе надо поковыряться в документации своего проекта или просто полюбоваться.
```
# Поднимем сервер на порту 6060
godoc -http=:6060
```
Потом тыкаешь в браузере http://localhost:6060/pkg/ и наслаждаешься, как будто на pkg.go.dev зашёл, только всё своё, родное.

И главное, не путай с этой всей Swagger-хуяггер!

godoc — это чтобы другой разработчик, который будет читать твой код, не послал тебя нахуй с первого взгляда. Документация для программистов.
Swagger/OpenAPI — это когда тебе надо объяснить какому-нибудь фронтендеру или мобильщику, куда тыкать в твоё API, чтобы что-то получить. Документация для потребителей твоего сервиса.

Вот и вся разница, ебать мои старые костыли.