可能な値が制限されたjsdocで文字列型を文書化する方法


96

1つの文字列パラメータを受け入れる関数があります。このパラメーターは、いくつかの定義可能な値のうちの1つのみを持つことができます。同じことを文書化する最良の方法は何ですか?shapeTypeは、列挙型、TypeDef、またはその他のものとして定義する必要がありますか?

Shape.prototype.create = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    this.type = shapeType;
};

Shape.prototype.getType = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    return this.type;
};

問題の2番目の部分は、の可能な値が、提案したものとしてshapeType定義shapeTypeされているファイルで不明であるということです。の可能な値に追加する可能性のある複数の開発者によって提供された複数のファイルがありますshapeType

PS:使用しています jsdoc3


複数ファイルの問題はこれを困難にします。私は通常enum、定義にforを、関数パラメーターに和集合を表示しますShapeType|string。ただし、列挙型は、Closure-compilerでの宣言後のサブタイプの追加をサポートしていません。
チャドキリングスワース2013

@ChadKillingsworth私はあなたが何を意味するのかわかります。プロパティのセット(クラスの構築パラメーターとして機能するオブジェクトなど)を定義したいところに行き詰まっています。構造のすべてのプロパティが1つの場所で定義されていれば、それは良好です。残念ながら、私のコードには、その構築プロパティに寄与するモジュールがいくつかあります。ミックスインのようなことをしたり、プロパティをサブクラス化したりすることは、やり過ぎになるでしょう!そのため、プロパティリストの定義を単純に挿入できれば、それは素晴らしいことです。
Shamasis Bhattacharya 2013

私が直面している別の同様の問題ですが、分散プロパティリストはstackoverflow.com/questions/19113571/…–
Shamasis Bhattacharya 2013

以下のすべてのソリューションでは、列挙型を作成する必要があります。このプロセスをはるかに簡単にするために、GitHubにアクティブな機能リクエストがあります:github.com/jsdoc3/jsdoc/issues/629。だから、それが好きな人はおそらくそれをぶつける必要があります。
B12Toaster 2016年

回答:


26

ダミーの列挙型を宣言するのはどうですか?

/**
 * Enum string values.
 * @enum {string}
 */
Enumeration = {
    ONE: "The number one",
    TWO: "A second number"
};

/**
 * Sample.
 * @param {Enumeration} a one of the enumeration values.
 */
Bar.prototype.sample = function(a) {};


b = new Bar();

bar.sample(Enumeration.ONE)

ただし、このためには、少なくともJSDOCに列挙型を宣言する必要があります。しかし、コードはクリーンであり、WebStormでオートコンプリートを取得します。

ただし、複数ファイルの問題はこの方法では解決できません。


はい。列挙アプローチは、私が見る唯一の使用可能な方法です。とにかく、私はこれを唯一の使用可能な答えとして受け入れます-マルチファイルの問題はまったく別の話なので!
Shamasis Bhattacharya 2013

このアプローチの問題は、個々の値を文書化できないことです。JSDocに問題があります。github.com/jsdoc3/jsdoc/issues/1065
Gajus

112

2014年後半のjsdoc3の時点で次のように書くことができます。

/**
 * @param {('rect'|'circle'|'ellipse')} shapeType - The allowed type of the shape
 */
Shape.prototype.getType = function (shapeType) {
  return this.type;
};

もちろん、これは専用の列挙型ほど再利用可能ではありませんが、多くの場合、ダミーの列挙型は1つの関数でのみ使用される場合はやり過ぎです。

参照:https//github.com/jsdoc3/jsdoc/issues/629#issue-31314808


4
paramタイプが決して変更されないことがわかっている場合、これはより良い解決策です。
Luca Steeb 2016年

1
私の見解では、これに対する最善の解決策です!ありがとうございました。
AJC24

26

どうですか:

/**
 * @typedef {"keyvalue" | "bar" | "timeseries" | "pie" | "table"} MetricFormat
 */

/**
 * @param format {MetricFormat}
 */
export function fetchMetric(format) {
    return fetch(`/matric}`, format);
}

ここに画像の説明を入力してください


9

許可された値を書く正式な方法はないと思います JSDocで

あなたは確かに前述の@param {String('up'|'down'|'left'|'right')}ユーザーb12toasterのようなものを書くことができます。

ここに画像の説明を入力してください

しかし、APIDocjsから参照することにより、制約付きの値を書き込むために使用するもの、別名allowedValuesを次に示します。ます。

/**
 * Set the arrow position of the tooltip
 * @param {String='up','down','left','right'} position pointer position
 */
setPosition(position='left'){
  // YOUR OWN CODE
}

そうそう、私はES6を使用しています。


0

これがClosureCompilerがサポートする方法です。「@ enum」を使用して制限付きタイプを定義できます。実際に列挙型定義で値を定義する必要はありません。たとえば、次のような「整数」型を定義できます。

/** @enum {number} */
var Int = {};

/** @return {Int} */
function toInt(val) {
  return /** @type {Int} */ (val|0);
}

Intは通常、「number」(数値)に割り当てることができますが、「number」は、何らかの強制(キャスト)がないと「Int」に割り当てることができません。


しかし、それはの可能な値を制限するものではありませんInt。それが可能かどうかはわかりません。
チャドキリングスワース2013年

これは、JSの他のタイプの注釈または列挙型と同じように機能します。制限は、コードの記述方法に起因します。すべての「キャスト」は危険信号です。キャストをバリューファクトリに制限すると、必要なものが得られます。警告なしに「number」を「Int」に割り当てることはできません。
ジョン

それでも{Int}の値は制限されません。:-(
Shamasis Bhattacharya 2013

確かに、Intの作成方法を制限することでIntの値を制限し、値の作成時に制限が行われます。必要なのは生の番号を割り当てることはできません。
ジョン
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.