このような JSDoc コメントを JavaScript ソースのどこにでも取り込めるようにしたいと考えています(関数の複数のレイヤー、モジュール、さらには無名関数にネストされていても):
/**
* Used to do some important thing that needs doing that works like xyz.
* @param {String} whatever - some string that has some purpose
* @param {Function} callback - a function that needs to be run
* @returns {Boolean} whether or not something happened
*/
function something(whatever, callback) {
...
そして、素敵なマークダウンを生成する簡単な方法があります:
##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.
*Parameters*
`whatever {String}` some string that has some purpose
`callback {Function}` a function that needs to be run
*Returns*
`{Boolean}` whether or not something happened
「ルート」は、その関数に到達可能な名前空間です。または、それが匿名関数またはプライベート関数である場合 (何らかの理由で public doco にある必要がありますが、それは理にかなっていますか??)、他の規則を使用してそれを示します。多分
##_private_function_ `something(whatever,callback)`
and
##_anonymous_function_`(whatever,callback)`
正確にその形式である必要はありません。Github で見栄えがよく、意味のあるものであればよいのです。理想的なツールは、 Mustache.jsのようなコードを取得して適切な出力を生成できるほどスマートなものです。また、多数のソース ファイルを処理し、出力として 1 つのドキュメントを生成するか、構成に応じてリンクされた一連のドキュメントを生成できる場合は、さらに優れています。
doco を更新するために非常に特殊なツールチェーンをセットアップする必要がないように、これを git リポジトリに完全かつ簡単に含めることができる方法で行うのが最善です。または、少なくとも最小限のツールチェーンが必要です。
ああ、そしてポニー。
既存のオプション
JSDoc、およびある種の HTML -> マークダウン変換
JSDoc はかなり良いです。しかし、モジュールでうまく機能させることができないようです。というか、それは私見である必要があるよりも大きな面倒です。関数に名前を付けるために余分なタグを追加する必要はありません。@export と @name を試してみましたが、最終的なドキュメントに希望どおりに表示するのにまだ問題があります。モジュールが含まれていてうまくできている JSDoc のコメント付きソースを誰かが指摘できれば、それが役立つかもしれません。 更新: JSDoc v3 は、実際には v2 よりもモジュールがはるかに優れているように見えるため、これの方が適している可能性があります。
思い通りの JSDoc 出力が得られたとしても、HTML からマークダウンに変換する必要があります。そのための適切なツールが見つからないようです。存在しますか?
ドックダウン
私はDocdownで少し遊んだが、それがPHPであるという事実は、私にとっては初心者のようなものだ...
YUIDocと変換
実際に YUIDoc で遊んだことはありませんが、問題ないようです。それでも、コンバーターが必要です。モジュールを簡単に処理し、関数名とエクスポート名を明示的に指定する必要がないようにしますか?
Doxとマークダウン テンプレート
Dox は出力として JSON を生成するため、それをいくつかの優れたマークダウン テンプレートと結合し、さらにドキュメントを生成するためのテンプレート エンジンを含める必要があります。このような一連のテンプレートを便利な方法でまとめた人はいますか?
jGrouse、および変換
ANT で動作します。次...
スクリプトドキュメント...
これはもう存在しますか？Aptanaスタジオの一部であるように見えるので、それは初心者ではありません.Aptanaはそれに関する情報を持っていないようです. しかし、ScriptDoc.org にはクラックに関する興味深い情報がいくつかあります。
Pdoc
Pdoc は Ruby ベースですが、そのツールチェーンは珍しいものではないため、大きな問題ではありません。独自のテンプレートを提供できるので、すでにいくつかの優れたマークダウン テンプレートがあるかもしれません。私はそれで遊んだことはありません...それは価値がありますか？そこに良いマークダウンテンプレートはありますか?
他の何か？
他に何がありますか？
自分で作ろう！
思い通りに動かそうと数時間 JSDoc をいじった後、私はあきらめて、私が取り組んできた Unicode JavaScript ライブラリであるCharFunkの Javaで、手早く汚いソリューションを書きました。まだ汎用に近いわけではありませんが、必要なものには十分に機能します。
そう.....
これは満たされていないニーズですか、それとも私だけですか?