2

カスタムコンテンツを生成するライブラリを作成しています。これは非常に冗長で、約 1100 行のコードです。コードは非常に読みやすく、厳密な命名規則に従っていますが、スクリプト ファイルを含めるときに使用できる API をどこに文書化すればよいかわかりません。ページにスクリプトを含める場合、intellisense は「パブリック」メソッドを取得しません。また、jQuery の場合も同様です。jQuery には API に関する素晴らしい Web サイト ( http://api.jquery.com/ ) がありますが、私はそれほど素晴らしいものを作る気はありません。

このカスタム API はどこに文書化すればよいですか?

コメントの場合、コメントのどのような構造をお勧めしますか?

編集

私のインテリセンスの要点は、優れた命名規則であっても文書化された API が必要になるということです。したがって、私は間違いなく一般的なアプローチに興味があります。

4

3 に答える 3

2

jsdoc はかなり人気があると思います。

http://code.google.com/p/jsdoc-toolkit/

リンクの規則に従って、インラインで文書化します。展開用に縮小/難読化された本番ビルドを配布し、開発用に文書化されたものを配布します（つまり、それを行うことができます）

編集、ここでさらにオプションを見つけることもできます: http://o2js.com/2011/05/01/how-to-document-a-javascript-framework/

于 2012-05-15T23:03:26.833 に答える
1

それはあなたのAPIがどれほど複雑かによって異なります.私自身の小さなライブラリでは、ファイルの上部に大きなコメントを付けます

  • これが何であるかの簡単な説明
  • ライブラリが html マークアップで動作する場合、コピーして貼り付けることができるいくつかのサンプル コード
  • パラメータを含む関数のリストと、それぞれの 1 行のドキュメント
  • ライブラリの一般的な使用例
  • 注意/警告/制限。人々が予期しない奇妙なことが常に起こっている

基本的に、これは C ヘッダー ファイルに入れるものです。

上記のすべてのことを別のファイルで実行してから、マークダウン構文を使用できると思います（私は怠け者です...また、すべてを単一のファイルに入れることを好みます）。

psインラインコメントについて言及する人もいます（つまり、関数が直接どこにあるか）。もちろんこれもオプションです。しかし、これはドキュメントが自動生成されている場合にのみ便利なようです。全体像が表示されないため、ファイル内のドキュメントをすばやく調べるには恐ろしい方法です。

于 2012-05-15T23:06:57.640 に答える
1

これは一般的なものではありませんが、エディターごとに個別のバージョンを維持することを気にしない場合は、Visual Studio の IntelliSense が JavaScript コード内の XML コメントを読み込んで解析します。MonoDevelop と SharpDevelop も同じファイルを使用できると思いますが、IntelliJ や Eclipse などの IDE がそれを利用できるとは思いません...

HTH。

于 2012-05-15T23:10:47.990 に答える