Как документировать строковый тип в jsdoc с ограниченными возможными значениями

Question

Как документировать строковый тип в jsdoc с ограниченными возможными значениями

у меня есть функция, которая принимает один строковый параметр. Этот параметр может иметь только одно из нескольких определенных возможных значений. Каков наилучший способ документировать то же самое? Должен ли 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;

};

вторая часть проблемы заключается в том, что возможные значения shapeType неизвестно в файле, который определяет shapeType а все, что вы предлагаете. Есть несколько файлов, внесенных несколькими разработчиками, которые могут добавить в возможные значения shapeType.

PS: я использую jsdoc3

684 5

google-closure-compiler google-closure jsdoc code-documentation

5 ответов:

Comments

Ничего не найдено.

Sebastian · Accepted Answer · 2013-10-11 19:09:51

Как насчет объявления фиктивного перечисления:
/**
 * 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.

проблема с несколькими файлами, хотя и не может быть решена таким образом.

B12Toaster · Accepted Answer · 2016-01-12 15:19:53

по состоянию на конец 2014 в jsdoc3 у вас есть возможность написать:
/**
 * @param {('rect'|'circle'|'ellipse')} shapeType - The allowed type of the shape
 */
Shape.prototype.getType = function (shapeType) {
  return this.type;
};
конечно, это будет не так многоразово, как выделенное перечисление, но во многих случаях фиктивное перечисление является излишним, если оно используется только одной функцией.

Смотрите также:https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Alan Dong · Accepted Answer · 2017-05-23 14:54:57

Я не думаю, что есть формальный способ записи допустимых значений в 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.

John · Accepted Answer · 2013-10-01 02:35:52

вот как компилятор закрытия поддерживает его: вы можете использовать "@enum" для определения ограниченного типа. На самом деле вам не нужно определять значения в определении enum. Например, я мог бы определить "число" типа:
/** @enum {number} */
var Int = {};

/** @return {Int} */
function toInt(val) {
  return /** @type {Int} */ (val|0);
}
Int обычно присваивается "number "(это число), но" number "не присваивается" Int " без некоторого принуждения (приведения).

puemos · Accepted Answer · 2018-09-19 11:14:07

о:

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

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