JavaScript Self-Documaning Code Где есть инструменты API DOCS?

Question

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

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

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

Answer 1

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

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