Вопрос по jsdoc, google-closure-compiler, code-documentation, google-closure – Как документировать строковый тип в 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

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

Ваш Ответ

5   ответов
0

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

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

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

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

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

Как насчет:

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

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

Это прекрасно работает с кодом ... scolestock
это неработать с Closure Compiler J.P. Duvet
3

Я нене думаю, что тамs формальный способ записи допустимых значений вJSDoc.

Вы, конечно, можете написать что-то вроде@param {String('up'|'down'|'left'|'right')} как пользовательb12toaster упоминается.

Но, взяв ссылку изAPIDocjs, Вот's, что я использую для записи ограниченных значений, иначеALLOWEDVALUES.

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

О да ям с помощью ES6.

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

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