web-dev-qa-db-ja.com

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

1つの文字列パラメーターを受け取る関数があります。このパラメーターは、いくつかの定義済みの可能な値のうちの1つのみを持つことができます。同じことを文書化する最良の方法は何ですか？ shapeTypeは、enumまたは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を使用しています

google-closure-compilergoogle-closurejsdoccode-documentation
64
Shamasis Bhattacharya

ダミー列挙型を宣言する方法は次のとおりです。

/**
 * 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で自動補完を取得します。

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

14
Sebastian

late 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

66
B12Toaster

どうですか：

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

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

enter image description here

7
puemos

JSDoc に許可された値を書き込む正式な方法はないと思います。

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

enter image description here

しかし、 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を使用しています。

3
Alan Dong

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

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

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

通常、Intは「number」（数値）に割り当て可能ですが、「number」は強制（キャスト）なしでは「Int」に割り当てられません。

0
John