JavaScript自己文書化コードAPIドキュメントツールはどこですか？

Question

これらの2つの概念は直感に反するようです。コメントが読みやすさに対して行われ、乾燥の違反に害を及ぼす害を感じる議論の片側があります（コメントが最新の状態に保たれている場合）。ただし、コインをひっくり返すと、他の人がライブラリを使用できるように、コードに優れたAPIドキュメントを提供する必要があります。

すべてのツール（JSDOC、PDOCなど）は、APIドキュメントを生成するために設計されていることがわかりました。これは、極端な量のスペースを使用してそのドキュメントを提供しています。 APIドキュメントを提供する必要があります。必要ではないのは、JSDOCが読むことができるように、私のLOCの半分を特別にフォーマットしたコメントにすることです。

私は現在、次のような基本的なマークダウンツールを検討しています ジキル このドキュメントをA /docフォルダーに入れて、コードから完全に削除します。他の誰かが彼らのために働いたこの問題へのアプローチを見つけましたか？

Answer 1

スフィンクス 多くの言語のドキュメントツールであり、主に外部ファイルでドキュメントを書くことを前提としています。それでもそれはあります autodoc コードのコメントからドキュメントを抽出できる拡張機能。

個人的には、APIドキュメントをコードのすぐ近くに置く方が便利だと思います。最新の状態に保つのに役立ちます。さらに、そのコードに取り組んでいる他の人々は、外部ファイルを閲覧することなく、必要なときにドキュメントを持つことができます。私は率直に言って、コメントであるほとんどのコードの行を持っていることで何も悪いことはありません。編集者は通常、コメントを異なって色付けし、必要に応じてそれらを無視できるようにします。