Sınırlı olası değerlerle jsdoc'ta bir dize türü nasıl belgelenir

Bir dize parametresini kabul eden bir işleve sahibim. Bu parametre, tanımlanmış birkaç olası değerden yalnızca birine sahip olabilir. Aynı şeyi belgelemenin en iyi yolu nedir? ShapeType, enum veya TypeDef veya başka bir şey olarak tanımlanmalı mı?

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;
};

Sorunun ikinci kısmı, önerdiğiniz her şeyi shapeTypetanımlayan dosyada olası değerlerinin bilinmemesidir shapeType. Çeşitli geliştiricilerin katkıda bulunduğu ve olası değerlerini ekleyebilecek birden çok dosya var shapeType.

Not: Kullanıyorum jsdoc3

Sahte bir enum beyan etmeye ne dersiniz:

/**
 * 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)

Ancak bunun için enum'u JSDOC'a bildirmeniz gerekir. Ancak kod temizdir ve WebStorm'da otomatik tamamlama elde edersiniz.

Birden çok dosya sorunu bu şekilde çözülemez.

İtibariyle 2014'ün sen yazma olanağına sahip jsdoc3 içinde:

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

Elbette bu, adanmış bir enum kadar yeniden kullanılabilir olmayacaktır, ancak çoğu durumda, yalnızca bir işlev tarafından kullanılıyorsa, kukla bir enum, aşırı bir değerdir.

Ayrıca bkz .: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Ne dersin:

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

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

JSDoc'da izin verilen değerleri yazmanın resmi bir yolu olduğunu sanmıyorum .

Kesinlikle b12toaster@param {String('up'|'down'|'left'|'right')} kullanıcısının bahsettiği gibi bir şey yazabilirsiniz .

Ancak, APIDocjs'den referans alarak , burada kısıtlı değerler yazmak için kullandığım şey, yani allowValues .

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

Oh evet, ES6 kullanıyorum.

Closure Compiler bunu şu şekilde destekler: kısıtlı bir türü tanımlamak için "@enum" kullanabilirsiniz. Aslında enum tanımındaki değerleri tanımlamanız gerekmez. Örneğin, şöyle bir "tamsayı" türü tanımlayabilirim:

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

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

Int genellikle "sayı" ya atanabilir (bu bir sayıdır), ancak "sayı", bazı zorlama (bir atama) olmaksızın "Int" ye atanamaz.