問題タブ [jsdoc]

JavaScript の文書化に JsDoc を使用しようとしてきましたが、このハードルに遭遇し続けています。「文書化するものは何もありません、終了します」と言い続けます

これが私が文書化しようとしているコードの一部です:

上記では名前空間を使用しています。JavaScript でバリアント形式の関数定義を使用しても、JSDoc はそれを認識しないようです。例えば：

これを回避する方法はありますか？ありがとう！

次のようなクラスがあるとします。

someFunctionが直接呼び出される関数ではなく、イベントハンドラーであることをJSDocに示す方法はありますか？

@eventタグが表示されますが、正しく理解していれば、これは、イベントハンドラーではなく、イベント（クライアントコードも登録され、必要に応じてクラスが起動するもの）と見なすクラス内の関数を文書化するためのものです。働き ？

私は特に JavaScript 匿名関数について言及していますが、これは他の言語にも当てはまる可能性があります。私は自分のスクリプトで JSDoc 表記を使用するのが好きです。他の人が遅かれ早かれ JSDoc 表記法をハッキングすることを知っているからです。非常に複雑な匿名関数がある場合、JSDoc または JavaDoc 表記法を理解する Eclipse やその他の IDE によって取得されるように、人々はそれをどのように文書化しますか?

ありがとう

次の Moo クラスがあります。

JsDocで文書化したい。@lends [class].prototype内部で使用できると読み、タグnew Classでマークinitializeします。@constructsメソッドやイベントをマークするにはどうすればよいですか?

IE:setHtmlContentsメソッドであるclose必要があり、イベントである必要があります。

また、どういうわけか、下の要素をoptions文書化できますか?

<code />JSDocになんらかのタグがあるか知っていますか？ドキュメントに次のようなコードを追加する必要があります。

コメント内のコードをJSDocによってコードとして表示する必要があります（構文が強調表示されていない場合は、少なくとも事前にフォーマットされているか、背景が灰色の何かのように）。

@paramブロックと@returnブロックの後に何かを書くことが可能かどうか知っていますか。パラメータ/リターン宣言の後に、それらから分離されたテキストを書きたいとしましょう。

JavadocとJsdocはどちらも、同じブロックのconetntsで@ param /@returnの後に書いたものをすべて添付しているようです。

たとえば、ドキュメントを次のように表示したいとします。

編集: これは技術的には 2 つの部分からなる質問です。一般的な質問をカバーする最良の回答を選択し、特定の質問を処理する回答にリンクしました。

jsdocで匿名オブジェクトと関数を文書化する最良の方法は何ですか?

PageRequestオブジェクトもcallbackコード内の存在もありません。それらはgetPage()実行時に提供されます。しかし、オブジェクトと機能が何であるかを定義できるようにしたいと考えています。

PageRequest次のことを文書化するためのオブジェクトを作成することから逃れることができます。

それは問題ありません (ただし、これを行うためのより良い方法を受け入れます)。

callback関数を文書化する最良の方法は何ですか? たとえば、コールバック関数が次の形式であることを文書で知らせたいと思います。

これを行う方法はありますか？

ソースコードにPHPDocとJSDocを使用しています。それらのドキュメントからAPIを構築するためのツールがあることを私は知っています。しかし、私が疑問に思っているのは、複雑なコードをどのように説明するのかということです。PHPDoc / JSDocで説明するのではなく、関数内で複数行コメントを使用するだけですか？

たとえば、次のコードについて考えてみます。

上記の場合、複雑なコードにコメントするにはどうすればよいですか？JSDocはAPIの構築に使用されるため（「動作方法」ではなく「使用方法」に関するものです）、JSDocではそれができないと思います。

私の仮定は正しいですか：

• JSDoc / PHPDocは、関数/メソッドを使用する人のためだけに書かれています。
• 関数内のコメントは、関数/メソッドの背後にあるロジックを理解する必要がある人のために書かれています。
• ドキュメントはAPIやソースコードのコメントとは別のものであり、（すべてのソフトウェアが提供する必要のある）ドキュメントはソフトウェアを使用したい人のために書かれています。

しかし、私が理解していないのは、アーキテクチャレベルでソフトウェアを説明しているのは何かということです。開発者向けのドキュメントも必要ですか？

ドキュメントを完成させるための戦略は何ですか？

可変数のパラメーターを文書化するにはどうすればよいですか？私はPHPとJavaScriptでアプリケーションを書いています。現在私は（JavaScriptで）持っています：

では、n-number of string paramsをどのようにドキュメント化するのですか？

Python コンポーネントと JavaScript コンポーネントを含むライブラリを文書化しています。全体的なユーザー ドキュメントと Python API ドキュメントは、Sphinx で処理された reStructuredText にあります。JavaScript API は jsdoc にあり、jsdoc-toolkit で処理されます。主な出力形式は HTML です。reST、Sphinx、jsdoc は初めてです。

生成されたすべての HTML ページが単一のディレクトリ ツリーにダンプされるように、ビルド システムをセットアップしました。ここで、メイン ページ (reST から生成) に、生成された Javascript ドキュメントへのリンクを挿入する必要があります。ドキュメントは異なるインストールの異なる場所にある可能性があるため、これは相対リンクである必要があります。reST は完全な URL を自動的に解析しますが、相対リンクを挿入する方法がわかりません。:ref:や:doc:のような構造は、ターゲットが reST であることを期待しているため、役に立たないようです。

何か案は？