1

require と jsdoc を使用して JavaScript モジュールから列挙型をエクスポートするための正規のパターンを知りたいです。既存の例と質問は、ローカルのプライベート列挙型のみを考慮しているようです。私の目標は、可能な限り最高品質のドキュメントとインテリセンス/コード補完を用意することです。

これが私の現在の最善の試みです：

var LawnMower = function () {
};

/**
* Enums for the valid heights to mow
* @readonly
* @enum {number}
*/
LawnMower.heights = {
    Low: 0,
    Medium: 1,
    High: 2
};

// Doing this separately from above, or Visual Studio's intellisense won't recognize it as an enum :-(
LawnMower.heights = Object.freeze(LawnMower.heights);

/*
 * @param {LawnMower.heights} height - The height of the deck on the mower
 */
LawnMower.prototype.mow = function (height) {};

module.exports = LawnMower;

このアプローチに私を導いたいくつかの詳細があります：

  1. 高さは列挙型です。静的です。
  2. Object.freeze がベスト プラクティスのようです。
  3. LawnMower.heights = Object.freeze(...) を実行すると、Visual Studio のインテリセンスが機能しなくなります。したがって、私は2つのステップでそれを行います。
  4. @readonly を追加しましたが、何もしないと思います
  5. mow() 関数は LawnMower.height を参照しますが、どのツールもそれをあまり処理していないようです。

私たちのチームは、Visual Studio、Ace+Tern、および Atom を使用しています。上記のパターンで、次のようなコードを書くと:

var lm = new LawnMower();
lm.mow(

インテリセンスがパラメーター名、型、および説明を表示することを期待しています。「LawnMower.heights」を記入するとボーナスポイント。私たちのために。(Visual Studio は C# に対してこれを行います)。

結果：

  • Atom はここで @param を完全に無視しているようです。
  • Visual Studio は、引数が高さであることを通知しますが、型や説明は提供しません。
  • Ace/Tern は高さの @jsdoc コメント行を表示します。

具体的な質問: @param 行を正しく書きましたか? 名前パス「LawnMower.heights」は、LawnMower の静的メンバーを参照する正しい方法だと思います。

参考文献:

  1. 可能な値が制限されている jsdoc で文字列型を文書化する方法
  2. JSDoc の @param 型としての列挙型
  3. 事前定義された一連の値を受け入れるパラメーターを文書化する方法は?
  4. http://usejsdoc.org/tags-enum.html
  5. http://usejsdoc.org/about-namepaths.html
4

0 に答える 0