web-dev-qa-db-ja.com

文書化されたJavaScript関数のGithubフレンドリーマークダウンを簡単に作成する方法

JavaScriptソースでanywhereのようにJSDocコメントを取得できるようにしたいです（複数の関数層、モジュール、または匿名関数にネストされている場合でも）：

/**
 *  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) {
     ...

niceマークダウンを作成する簡単な方法があります。

##`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

「ルート」は、その関数が到達可能な名前空間です。または、匿名関数またはプライベート関数（何らかの理由で公共のドコにあるべきなのに、それは理にかなっていますか？）である場合、他の規則を使用してそれを示します。多分

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

必ずしもその形式である必要はなく、Githubで見栄えが良く、意味のあるものである必要があります。理想的なツールは、 Mustache.js のようなコードを取得して適切な出力を生成できるほどスマートです。さらに、多くのソースファイルを処理し、1つのドキュメントを出力として作成できる場合、または構成に応じてドキュメントのリンクセットを作成できる場合はさらに便利です。

そして、これをgitリポジトリに完全かつ簡単に含めることができる方法で行うと、人々がドコを更新するために高度に特定のツールチェーンをセットアップする必要がなくなるのが最善です。または、少なくとも最小限のツールチェーンが必要です。

ああ、ポニー。

既存のオプション

JSDoc 、および何らかのHTML->マークダウン変換

JSDocはかなり優れています。しかし、私はそれをモジュールでうまく動作させることができないようです。むしろ、それは私見であるべき以上に大きな面倒です。関数に名前を付けるために追加のタグを追加する必要はありません。 @exportと@nameを試してみましたが、最終的なドキュメントに希望どおりに表示するのにまだ苦労しています。誰かがその中にモジュールを持ち、うまく行われているJSDocコメント付きソースを指すことができるなら、それは助けになるかもしれません。 更新：JSDoc v3は実際にはv2よりもモジュールのほうがはるかに優れているように見えるので、これがより適しているかもしれません。

私が望むようにJSDoc出力を取得できたとしても、HTMLからマークダウンに変換する必要があります。そのための良いツールが見つからないようですが、存在しますか？

ドックダウン

私はDocdownで少し遊びましたが、それがPHPであるという事実は私にとってはちょっとした初心者です...

YUIDoc 、プラス変換

実際にYUIDocで遊んだことはありませんが、大丈夫そうです。それでも、コンバータが必要です。モジュールを簡単に処理し、関数名とエクスポート名を明示的に指定する必要はありませんか？

Dox 、およびマークダウンテンプレート

Doxは出力としてJSONを生成するので、それを適切なマークダウンテンプレートと結合する必要があり、さらにドキュメントを生成するテンプレートエンジンを含める必要があります。誰もがそのようなテンプレートのセットを便利な方法でまとめましたか？

jGrouse 、プラス変換

ANTで実行します。次...

ScriptDoc ...

これはもう存在しますか？ Aptanaスタジオの一部のように思えるので、それはスターターではないでしょう... Aptanaは、それに関する情報を何も知らないようです。ただし、ScriptDoc.orgには、クラックに関する興味深い情報があります。

Pdoc

PdocはRubyベースですが、そのツールチェーンは珍しいことではないので大きな問題ではありません。独自のテンプレートを提供することができます。 ..それは価値がありますか？良いマークダウンテンプレートはありますか？

他に何か？

他に何がありますか？

自分で作ろう！

数時間JSDocをいじり回して、思い通りに動作させようとして、あきらめて、 Javaで自分の迅速で汚い解決策を書きました for CharFunk 、Unicode私が取り組んできたJavaScriptライブラリ。まだ一般的な目的に近いわけではありませんが、私が必要とするものには十分に機能します。

そう.....

これは満たされていないニーズですか、それとも私だけですか？

javascriptgithubmarkdownjsdoc
60
jwl

試してみました jsdox ？

Node.js jsdocからマークダウンジェネレーターへ。

13
Steven de Salas

jsdoc-to-markdown ..を使用します.

文書化されたコードを書く：

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

マークダウンドキュメントを取得：

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

これらのプロジェクトには、jsdoc2md：

18
Lloyd

markdox は、javascriptコードからマークダウンドキュメントを生成できます。

7
user2367031

jsDox。 https://github.com/sutoiku/jsdox UglifyJSを使用した完全な解析

モックス。 https://github.com/tjchaplin/mox すぐに実行できるいくつかのサンプル/テンプレート。

どちらもJSDoc/Dox形式を処理します。どちらも活発な開発が行われています。私にとっては、サンプルスイートのおかげでMoxが勝ちます。

3
Chris Buck

OK。自分で熟考した後、Node上のDOX + Underscore/Whatever JSテンプレートエンジンを使用しました。

かなりシンプルなはずです。おそらく、Gruntなどにジャムして、監視タスクの下で実行することもできます。

Doxは、覚えている限りでは比較的軽量で、npmパッケージ（IIRC）があります。

更新：ある程度の経験の後、YUIDocへの回答を変更したいと思います。

2
ZenMaster

JSDocからAPIドキュメントを作成する必要がありました。このドキュメントは使いやすく、最新のフロントエンドスタックもサポートする必要があります。言及されたライブラリの一部には、BabeljsにトランスポートされたJSコードに問題があるため、マークダウンドキュメントを生成するために、一時的にコードをコメントでトランスラップする必要があります。

そのようなユースケースでは、BavelJs構成のサポートが統合されているため、JSDocsからマークダウン（JSON、HTML）を生成するので http://documentation.js.org/ が非常に有用であることがわかりました。

0
Fer To

動詞 を使用してみてください。最も単純なユースケースでは、Verbはpackage.jsonのデータを使用してテンプレートからreadmeを作成します。

ただし、複数ページの目次を生成したり、カスタムヘルパーを作成したりする必要がある場合、動詞には高度な機能もあります。

APIドキュメントについては、これを参照してください readmeの例index.js。見出しをクリックすると、それらも自動生成されます。 この組み込みヘルパー を使用して、指定されたファイルパスからAPIドキュメントを生成します。 globパターンを使用して、複数のファイルからドキュメントを取り込むこともできます。

動詞は.verb.md設定なし。しかし、さらに必要な場合は、 verbfile.js を使用できます

0
jonschlinkert