問題タブ [jsdoc3]

私は自分の JS ドキュメントを正しく取得しようとしています。私は Dojo と、その上に構築された他の複雑なフレームワークを使用しています。詳細は省きます。ポイントは、このフレームワークが AMD モジュールを使用していることです。JSDoc を機能させたい。

これが私がこれまでに持っているものです：

結果：

この結果は悪くない。しかし、それは私のメンバーが静的であることを示唆しています。WebStorm はそれらをメンバーとして正しく推測しているようですが、jsdoc3 ジェネレーターはそうではありません。私が読んだことから、@lendsがそれを処理する必要があるため、@memberofを指定する必要はありません。私が間違っていることはありますか？一般的な推奨事項をいただければ幸いです。JSDoc3 のドキュメントを読みましたが、AMD を式に追加すると、多くの構造がぼやけて見えます。

npm から JSDoc と JSDoc 3 Tool をインストールしました。

ソフトウェアが正常にインストールされ、コマンド ( jsdoc -r=doc file.js ) が実行され、ファイルを含むフォルダーが生成されました。

ただし、マークアップは無視され、index.html はグローバルクラスを記述する次のパスにのみリンクします。

私はどこに迷い込んだのですか？

JSDoc には@readonlyドックレット タグがあります。

@readonly タグは、シンボルが読み取り専用であることを示します。

例えば：

ただし、私が実際に伝えて文書化したいのは、パブリック コンシューマはプロパティを読み取り専用として扱う必要があるということですが、メンバーは一定ではありません。

内部コードはそのようなメンバーを変更できますし、実際に変更します。読み取り専用のドックレット タグは API コンシューマ用です。(そして、API が間違って使用された場合、恥を知れ! - しかし、私の懸念ではありません。)

この概念を JSDoc (タグ) で表現する良い方法はありますか? 特に、

「内部コードがこの読み取り専用メンバーを変更することが期待されます」を表現する良い方法は何ですか?

もちろん、ドキュメントでは、ドックレットタグを除いて、そのような明示的な記述は必要ありません。

私は当初、JSDoc が "@readonly private" などを自明に受け入れることを望んでいましたが、そうではありません。カスタム タグを使用する際の問題は、そのようなタグがローカルに導入され、差し迫った外部の意味や標準テンプレートでの適用がないことです。

として追加されたプロパティの JSDoc ドキュメントを追加したいと考えていますObject.defineProperty。このようなものがうまくいくと思います：

しかし、生成された JSDoc の説明には、次のプロパティがありません。

この種のプロパティを文書化するための最も適切なアプローチは何ですか? (プラグインかな？)

引数 (オブジェクト) とそのすべてのプロパティを文書化する適切な方法は何だろうと思っていました。

1. 角括弧が「オプション」を意味することを正しく理解していれば、そうですか？
2. オブジェクトのプロパティを記述するために使用した構文は有効ですか?
3. プロパティは数値ですが、そのreqSettings.retryInterval単位を含める方法が見つかりませんでした。この数値がミリ秒であることを示す方法はありますか?

コード：

何らかの形で JSDoc を使用して関数のエディターのオートコンプリートを取得できますか?

関連するスクリプト エディタで大量のコードを含む大きな Google スプレッドシートを作成しています。

LINE 1 にピリオドを書き込むとオートコンプリート ヘルプが表示されますが (以下のコードを参照)、LINE 2 にピリオドを書き込むとオートコンプリート ヘルプが表示されます。

これを通常の JavaScript オブジェクトやスプレッドシート関連のオブジェクトで機能させることに成功していません。両方に興味があります。

オプションの JavaScript パラメータを文書化するための適切な構文はありますか。オプションのパラメータは関数ヘッダーの途中にあります (jQuery、Gulp などを考えてください)。

私は標準的な方法で関数を文書化しましたが、それはうまくいきます。問題は、2 番目のパラメーターを最後の変数に設定しようとすると (オプションのパラメーターが使用されなかった場合)、IDE が混乱することです。

例：

問題があれば、私は JetBrains の PHPStorm を使用しています。これは、(主に) Google Closure スタイルのドキュメントを使用しています。私はより一般的なベストプラクティスのアプローチを探していますが。

次のような醜いことができると思います：

しかし、それは私が望むほど正確に状況を説明しているわけではありません。これが一般的な構造になりつつあるので、適切に処理する何かがあることを願っています。