Если вы не верите, что ваш код самодокументирован, и следуете правилу, согласно которому документация является неотъемлемой частью хорошего проекта, возможно, вы найдете здесь несколько интересных моментов о создании документации из комментариев к коду.
Очень здорово, что есть такие отличные проекты, как sphinx или jsdoc, которые помогают нам легко генерировать удобочитаемую документацию из исходного кода.
И ниже некоторые мои рекомендации, как заполнить документацию по коду с помощью jsdoc
.
- Используйте плагин ink-docstrap. Он предоставляет классные настраиваемые темы.
- Используйте плагин для обработки async/await, так как текущая версия jsdoc не поддерживает его.
- Включить
README.md
вjsdoc
конфиг.README
— это лицо вашего проекта и должно быть понятным. - Включить
tutorials
вjsdoc
конфиг. Там вы можете описать темы, которые слишком длинны дляREADME
. - Начните
README
с краткой аннотации, почему и что представляет собой ваш проект. - Добавьте раздел
Features
и перечислите там все важные функции проекта. Если его возможности описаны вtutorials
, добавьте туда ссылку. - Укажите раздел
How to install
. Опишите, какое бинарное или стороннее программное обеспечение требуется. - Предоставьте раздел
Quick start
. Постарайтесь сделать это как можно проще. Это поможет пользователям легче понять проект. - Предоставьте раздел
Options
и опишите тамCLI
опции например, с вариантами использования. - Предоставьте раздел
Guidelines
илиHow to
и включите туда ссылки, как решить некоторые типичные проблемы с вашим проектом. - Не стесняйтесь использовать гиперссылки, это облегчит навигацию по документации.
- На
tutorials
странице поддержкиrelease-notes
добавьте ссылку наREADME
. - Максимально используйте тег
@example
, чтобы показать, как будут использоваться запланированные вами функции. - Используйте тег
@ignore
для внутренних функций, которых не должно быть в документации. Не выбрасывайте это. - Используйте тег
@deprecated
, чтобы отметить функции, которые не следует использовать.
Некоторые проекты с классной документацией по коду: