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

Question

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

Comments

कई फाइलों की समस्या इसे मुश्किल बना देती है। मैं आमतौर पर enumफ़ंक्शन पैरामीटर के लिए परिभाषा और एक संघ के लिए देखता हूं ShapeType|string:। हालाँकि एनमोज़ क्लोजर-कंपाइलर में घोषणा के बाद सबटिप जोड़ने का समर्थन नहीं करता है।

— चाड किलिंग्सवर्थ

@ChadKillingsworth मैं देख रहा हूं कि आपका क्या मतलब है। मैं उस बिंदु पर अटका हुआ हूं, जहां मैं गुणों के एक सेट को परिभाषित करना चाहता हूं (किसी ऑब्जेक्ट को एक वर्ग के निर्माण पैरामीटर के रूप में जाने देता है)। यह अच्छी तरह से और अच्छा है निर्माण के सभी गुणों को एक स्थान पर परिभाषित किया गया था। दुर्भाग्य से, मेरे कोड में उस निर्माण गुण में योगदान करने वाले कई मॉड्यूल हैं। एक मिश्रण की तरह कुछ कर या उपशम उपवर्ग को ओवरबोर्ड करते हुए किया जाएगा! जैसे, अगर मैं बस एक संपत्ति सूची की परिभाषा को इंजेक्ट कर सकता हूं तो यह बहुत अच्छा होगा।

— शमसिस भट्टाचार्य

इसी तरह का एक और मुद्दा जिसका मैं सामना कर रहा हूं, लेकिन वितरित संपत्ति लिस्टिंग के साथ stackoverflow.com/questions/19113571/…

— Shamasis Bhattacharya

नीचे दिए गए सभी समाधान हमें एनम बनाने के लिए मजबूर करते हैं। इस प्रक्रिया को और अधिक आसान बनाने के लिए GitHub में एक सक्रिय सुविधा अनुरोध है: github.com/jsdoc3/jsdoc/issues/629 । इसलिए जो कोई भी इसे पसंद करता है, उसे शायद इसे टक्कर देनी चाहिए।

— B12Toaster

Answer 1

कैसे एक डमी की घोषणा के बारे में:

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

आपको कम से कम जेएमओएसओसी को एनम घोषित करना होगा, हालांकि इसके लिए। लेकिन कोड साफ है और आपको WebStorm में स्वतः पूर्णता प्राप्त होती है।

एकाधिक फ़ाइलों की समस्या हालांकि इस तरह हल नहीं की जा सकती।

Comments

हाँ। गणना दृष्टिकोण ही एकमात्र उपयोगी तरीका है जिसे मैं देख रहा हूं। वैसे भी, मैं इसे केवल प्रयोग करने योग्य उत्तर के रूप में स्वीकार करता हूं - क्योंकि बहु-फ़ाइल समस्या पूरी तरह से एक और कहानी है!

— शामसी भट्टाचार्य

इस दृष्टिकोण के साथ समस्या यह है कि यह व्यक्तिगत मूल्यों को दस्तावेज करने की अनुमति नहीं देता है। मेरे पास JSDoc के साथ एक मुद्दा है। github.com/jsdoc3/jsdoc/issues/1065

— गजस

Answer 2

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

/**
 * @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-313148080

Comments

यह एक बेहतर समाधान है यदि आप जानते हैं कि परम प्रकार कभी नहीं बदलेगा।

— लुका स्टीब

मेरे विचार में इसके लिए सबसे अच्छा समाधान! धन्यवाद।

— एजेसी

Answer 3

व्हाट अबाउट:

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

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

Answer 4

मुझे नहीं लगता कि JSDoc में अनुमत मूल्यों को लिखने का एक औपचारिक तरीका है ।

आप निश्चित रूप से @param {String('up'|'down'|'left'|'right')}उपयोगकर्ता b12toaster उल्लेख की तरह कुछ लिख सकते हैं ।

लेकिन, APIDocjs से संदर्भ लेने से , यहाँ मैं विवश मूल्यों को लिखने के लिए क्या उपयोग करता हूं, उर्फ अनुमतियाँ हैं ।

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

ओह, मैं ES6 का उपयोग कर रहा हूं।

Answer 5

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

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

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

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

Comments

लेकिन यह संभव मूल्यों को प्रतिबंधित नहीं करता है Int। यह हिस्सा मुझे यकीन नहीं है कि संभव है।

— चाड किलिंग्सवर्थ

यह जेएस में किसी भी अन्य प्रकार के एनोटेशन या एनम के रूप में ज्यादा है। प्रतिबंध इस बात से है कि आप कोड कैसे लिखते हैं: प्रत्येक "कास्ट" एक लाल झंडा है। यदि आप जातियों को मूल्य कारखानों तक सीमित कर देते हैं तो आपको वही मिलता है जो आप चाहते हैं: आप चेतावनी के बिना 'इंट' को 'संख्या' नहीं दे सकते।

— जॉन

यह अभी भी {Int} के मूल्यों को प्रतिबंधित नहीं करता है। :-(

— शमिस भट्टाचार्य

यह सुनिश्चित करता है कि, आप Int के मान को सीमित करके सीमित करते हैं कि यह कैसे बनाया जाता है और मूल्य बनाए जाने पर प्रतिबंध लगाया जाता है। एक कच्ची संख्या को असाइन नहीं किया जा सकता है, जिसकी आपको आवश्यकता है।

— जॉन