Вопрос по jsdoc, google-closure-compiler, google-closure, code-documentation – Как документировать строковый тип в jsdoc с ограниченными возможными значениями

59

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

Еще одна похожая проблема, с которой я сталкиваюсь, но с распределенным списком свойствstackoverflow.com/questions/19113571/... Shamasis Bhattacharya
@ChadKillingsworth Я понимаю, что вы имеете в виду. Я застрял в точке, где я хочу определить набор свойств (скажем, объект, который идет в качестве параметра конструкции класса). Хорошо, что все свойства конструкции были определены в одном месте. К сожалению, в моем коде есть несколько модулей, способствующих этим свойствам конструкции. Делать что-то вроде миксина или подкласса имущих имело бы слишком много времени! Таким образом, если бы я мог просто внедрить определение списка свойств, было бы здорово. Shamasis Bhattacharya
Проблема с несколькими файлами делает это трудным. Я обычно вижуenum для определения и объединения для параметра функции:ShapeType|string, Однако перечисления не поддерживают добавление подтипов после объявления в Closure-compiler. Chad Killingsworth
Все приведенные ниже решения заставляют нас создавать Enum. На GitHub есть запрос на активную функцию, чтобы сделать этот процесс намного проще:github.com/jsdoc3/jsdoc/issues/629, Таким образом, любой, кто любит это, должен вероятно натолкнуть это. B12Toaster

Ваш Ответ

5   ответов
58

По состоянию наконец 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

Это должен быть принятый ответ. ııı
Это лучшее решение, если вы знаете, что тип параметра никогда не изменится. Luca Steeb
15

Как насчет объявления фиктивного перечисления:

/**
 * 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
Проблема этого подхода заключается в том, что он не позволяет документировать отдельные значения. У меня проблема с JSDoc.github.com/jsdoc3/jsdoc/issues/1065 Gajus
Имеет смысл добавить @readonly к перечислению mPrinC
3

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

вы можете использовать «@enum» для определения ограниченного типа. На самом деле вам не нужно определять значения в определении enum. Например, я мог бы определить «целочисленный» тип как:

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

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

Int обычно присваивается «номеру» (это число), но «число» не присваивается «Int» без некоторого принуждения (приведение).

Он делает столько же, сколько любые другие аннотации или перечисления в JS. Ограничение исходит из того, как вы пишете код: каждый «бросок» - это красный флаг. Если вы ограничите приведение значений фабриками, то получите то, что хотите: вы не можете присвоить «число» для «Int» без предупреждения. John
Но это не ограничивает возможные значенияInt, Я не уверен, что это возможно. Chad Killingsworth
Это все еще не ограничивает значения {Int}. :-( Shamasis Bhattacharya
Конечно, вы ограничиваете значение Int, ограничивая его создание, и ограничение выполняется при создании значения. Сырой номер не может быть назначен, и это все, что вам нужно. John
4

Что о:

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

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

Похожие вопросы