x-doc-go

name	x-doc-go
description	Применяй при создании нового пакета или изменении существующего package contract: наличие `doc.go`, структура package comment, секция `Конфигурация`, ограничения, doc-комментарии экспортируемых символов и тестируемые примеры `Example...`

doc.go

Если нужен быстрый smoke-check пакета, используй scripts/check-doc-go.sh <package-dir>.

Шаг 1: Проверь наличие doc.go

Каждый пакет и подпакет обязан иметь doc.go. Если его нет — создай.

Исключения — doc.go не требуется:

• cmd/app/ и другие cmd/* пакеты — точки входа приложения, не имеют переиспользуемого контракта.
• mocks/ - это автогенерация.

Шаг 2: Прочитай doc.go перед началом работы

doc.go — это контракт пакета. Читай его первым при входе в любую директорию пакета.

Шаг 3: Напиши или обнови package-level комментарий

Комментарий должен содержать четыре секции:

1. Что реализует — какой интерфейс и из какого пакета
2. Точка входа — какой конструктор использовать
3. Переменные окружения — список с дефолтами
4. Ограничения — потокобезопасность, обязательный Close(), порядок вызовов

// Package {name} реализует интерфейс {parent}.{Interface} для {Service}.
//
// Использование:
//
//	instance := {name}.New(cfg)
//	defer instance.Close()
//
// Конфигурация:
//
//	{ENV_VAR_1}  — описание (default: value)
//	{ENV_VAR_2}  — описание (default: value)
//
// Ограничения:
//
//	- Потокобезопасность: да/нет
//	- Требует Close() для освобождения ресурсов
//	- {другие ограничения}
package {name}

Шаг 4: Проверь doc-комментарии экспортируемых символов

Каждый экспортируемый тип, функция и метод обязан иметь doc-комментарий — полное предложение на русском, заканчивается точкой (см. AGENTS.md, Global Conventions).

Формат: // ИмяСимвола описание действия.

// CreatePoint создаёт точку с заданными координатами.
func (s *Service) CreatePoint(ctx context.Context, x, y float64) (*domain.Point, error) {

Исключения — doc-комментарий не требуется:

• Методы, сгенерированные кодогенератором (gqlgen, protoc и т.д.)
• Неэкспортируемые символы (начинаются с маленькой буквы)

Проверка — найди экспортируемые символы без doc-комментария:

rg -n "^(func|type) " -g '*.go' -g '!**/*_test.go' -g '!**/mocks/**' .

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

Шаг 5: Синхронизируй с кодом

doc.go должен отражать актуальное состояние пакета. При каждом PR — проверь что переменные окружения, конструктор и ограничения актуальны.

Шаг 6: Добавь тестируемые примеры, если они заменяют документационный сниппет

Если публичный контракт пакета, функции или типа проще понять через короткий рабочий пример, оформи его как Go example test:

• Example() — пример пакета
• ExampleFunc() — пример функции Func
• ExampleType() — пример типа Type
• ExampleType_Method() — пример метода Type.Method

Пример должен жить в *_test.go рядом с пакетом и печатать наблюдаемый результат. Ожидаемый вывод фиксируй в комментарии Output: — тогда go test проверит, что пример не устарел.

func ExampleNormalizeName() {
	fmt.Println(NormalizeName("  Alice  "))
	// Output: Alice
}

Используй Example..., когда иначе пришлось бы вставлять в doc.go или doc-комментарий проверяемый фрагмент кода с ожидаемым результатом. Не добавляй примеры ради формальности: для очевидных конструкторов и boilerplate достаточно обычного раздела Использование в doc.go.

Пример

// Package redis реализует интерфейс kv.Store для Redis.
//
// Использование:
//
//	store := redis.New(cfg)
//
// Конфигурация:
//
//	REDIS_ADDR     — адрес сервера (default: localhost:6379)
//	REDIS_PASSWORD — пароль
//	REDIS_DB       — номер базы данных (default: 0)
package redis

Эталонные варианты doc.go для разных типов пакетов

Корневой пакет конфигурации

• пакет сразу объясняет, что конфиг грузится из окружения
• перечисляет верхнеуровневые переменные
• не расписывает до бесконечности вложенные платформенные конфиги, а даёт ориентир, где смотреть дальше

Это хороший паттерн для корневого Config приложения.

Длинный прикладной список переменных окружения

• допустим, когда пакет реально владеет большим количеством прикладных переменных
• в таком случае длинная секция Конфигурация — часть контракта, а не шум

Используй этот стиль, когда у пакета много собственных env и они нужны как явный публичный договор.

Legacy-совместимость

• можно явно описывать устаревшие алиасы
• нужно указывать приоритет новых переменных
• миграция env — это часть контракта пакета, если она реально поддерживается

Что должно читаться сразу

Хороший doc.go позволяет за минуту понять:

• что делает пакет
• какая у него точка входа
• какие env нужны
• какие ограничения или правила жизненного цикла нельзя нарушать

Не делай

• не заменяй doc.go на README.md внутри пакета
• не оставляй doc.go в состоянии, которое уже не совпадает с кодом
• не пропускай секцию Ограничения, если пакет требует Close(), lifecycle или special order of calls
• не пиши doc-комментарии экспортируемых символов на английском

Полезные ресурсы

• scripts/check-doc-go.sh — проверка наличия и базовой структуры doc.go