Определите читателя: пользователь библиотеки, новый разработчик или сопровождающий модуль.
Зачем
Зачем это нужно
Передайте код и контракт; попросите пример обычного вызова и одного значимого ошибочного случая.
Запустите пример, сверьте имена и значения по умолчанию, затем уберите утверждения без основания.
Вопросы
Частые вопросы
Что писать в комментарии, а что в руководстве?
Рядом с кодом полезно объяснять нетривиальную причину решения и ограничения. Руководство показывает сценарий использования и настройку. Не пересказывайте каждую строку: это мешает увидеть контракт и быстро устаревает.
Как документировать неполный фрагмент?
Прямо укажите, что известно только из переданного кода, а какие зависимости не показаны. Попросите список вопросов к автору вместо догадок. Например, обработка ошибки внешней службы может находиться в другом слое.
Как поддерживать примеры актуальными?
Используйте маленькие примеры на публичном интерфейсе и включайте их проверку в ваш процесс разработки. После изменения сигнатуры, конфигурации или ошибок пересмотрите связанные инструкции. Успешное чтение документации не заменяет запуск примера.
Рядом
Соседние страницы каталога
Дальше — весь каталог задач: поиск по названию, темы и фильтры.