JavaScript Самодокументированный код, где инструменты API Docs?

Question

Эти два понятия кажутся нелогичными.Есть одна сторона аргумента, которая видит вред, который комментарии наносят читабельности, и нарушениям DRY (если комментарии даже обновляются).Однако переверните монету, и вам необходимо предоставить хорошую документацию по API для вашего кода, чтобы другие могли использовать ваши библиотеки.

Каждый инструмент (JSDoc, PDoc и т. Д.), Который я видел, предназначен для генерации APIДокументы используют чрезвычайно много места для предоставления этой документации.Мне нужно предоставить документацию по API, но мне не нужно, чтобы половина моего LOC была специально отформатирована, чтобы JSDoc мог ее прочитать.

В настоящее время я рассматриваю базовый инструмент уценки, такой как Jekyll и помещаю эту документацию в папку / doc, полностью удаляя ее из моего кода.Кто-нибудь еще нашел подход к этой проблеме, который работал для них?

Answer 1

Sphinx - инструмент документации для многих языков, который предполагает, что вы будете писать свою документацию в основном во внешних файлах.Тем не менее он имеет расширение autodoc, которое позволяет извлекать документацию из комментариев в коде.

Лично мне удобнее иметь документацию API рядом с кодом, поскольку это помогает мне поддерживать егона свидание.Более того, другие люди, работающие над этим кодом, смогут получать документацию именно тогда, когда им это нужно, без необходимости просматривать внешние файлы.Честно говоря, я не вижу ничего плохого в том, чтобы большинство строк кода были комментариями: редакторы обычно окрашивают комментарии по-разному и позволяют игнорировать их, если хотите.