Если вы не верите, что ваш код самодокументирован, и следуете правилу, согласно которому документация является неотъемлемой частью хорошего проекта, возможно, вы найдете здесь несколько интересных моментов о создании документации из комментариев к коду.

Очень здорово, что есть такие отличные проекты, как 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, чтобы отметить функции, которые не следует использовать.

Некоторые проекты с классной документацией по коду: