google closure compiler - सीमित संभावित मानों के साथ jsdoc में स्ट्रिंग प्रकार को कैसे दस्तावेज़ित करें




google-closure-compiler google-closure (4)

मेरे पास एक ऐसा फ़ंक्शन है जो एक स्ट्रिंग पैरामीटर स्वीकार करता है। इस पैरामीटर में कुछ परिभाषित संभावित मानों में से केवल एक हो सकता है। दस्तावेज करने का सबसे अच्छा तरीका क्या है? आकार टाइप करना चाहिए 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 कि आप सुझाते हैं। कई डेवलपर्स द्वारा कई फाइलें योगदान दी गई हैं जो आकार प्रकार के संभावित मानों को जोड़ सकती हैं।

पीएस: jsdoc3 का उपयोग कर रहा हूँ


इस प्रकार क्लोजर कंपाइलर इसका समर्थन करता है: आप प्रतिबंधित प्रकार को परिभाषित करने के लिए "@enum" का उपयोग कर सकते हैं। आपको वास्तव में enum परिभाषा में मानों को परिभाषित नहीं करना है। उदाहरण के लिए, मैं एक "पूर्णांक" प्रकार को परिभाषित कर सकता हूं जैसे:

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

इंट आमतौर पर "संख्या" के लिए असाइन करने योग्य होता है (यह एक संख्या है) लेकिन "संख्या" कुछ दबाव (एक कास्ट) के बिना "Int" को असाइन करने योग्य नहीं है।


एक डमी एनम घोषित करने के बारे में:

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

यद्यपि, इसके लिए आपको जेएसडीओसी को कम से कम घोषित करने की आवश्यकता है। लेकिन कोड साफ़ है और आप वेबस्टॉर्म में ऑटो-पूर्णता प्राप्त करते हैं।

हालांकि कई फाइलें समस्या हल नहीं की जा सकती हैं।


व्हाट अबाउट:

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

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


2014 के अंत तक jsdoc3 में आपके पास लिखने की संभावना है:

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

बेशक यह एक समर्पित enum के रूप में पुन: प्रयोज्य नहीं होगा लेकिन कई मामलों में एक डमी enum एक overkill है अगर यह केवल एक समारोह द्वारा उपयोग किया जाता है।

यह भी देखें: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808





code-documentation