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

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

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

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

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

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

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

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

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

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

2. Запуск локального сервера документации: Для просмотра документации в браузере, аналогично pkg.go.dev.

   # Запустит сервер на порту 6060
   godoc -http=:6060

   После этого можно открыть в браузере http://localhost:6060/pkg/ и навигироваться по документации ваших локальных проектов и стандартной библиотеки.

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

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