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

Question

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

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

I'm currently considering a basic markdown tool like Jekyll and putting this documentation in a /doc folder, totally removing it from my code. Has anyone else found an approach to this problem that has worked for them?

Answer 1

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

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