क्या JSDoc "@method" एनोटेशन

Question

का उपयोग करने से बचने का कोई तरीका है मैं व्यक्तिगत रूप से जेनरेट किए गए दस्तावेज़ों का एक बड़ा प्रशंसक नहीं हूं (मैं "स्रोत ल्यूक" थोडा लड़का पढ़ता हूं), लेकिन मैं देख सकता हूं कि कैसे ऐसे दस्तावेज दूसरों के लिए उपयोगी हो सकते हैं। अब, आम तौर पर उनके प्रलेखन का उत्पादन मुझे प्रभावित नहीं करेगा, एक चीज़ को छोड़कर: @ method।

अधिकांश JSDoc एनोटेशन (जैसे @param।) अभी भी पूरी तरह से किसी स्रोत को पढ़ने के लिए उपयोगी होते हैं, लेकिन @method 100% अनावश्यक है:

/* 
* @param num number to add five to 
* @method addFive 
*/ 
function addFive(num) { ... 

तो, मैं वास्तव में @method लाइनों के सैकड़ों होने से बचाने के लिए करना चाहते हैं हमारे कोड को अपनाना। हालांकि, मेरे सहकर्मी का मानना ​​है कि कक्षाओं की विधि सूचियां उत्पन्न करने में सक्षम होने के लिए जेएसडीओसी जेनरेटर (वह यूयूआई का उपयोग कर रहा है) के लिए @method आवश्यक है।

तो, मेरा प्रश्न (जेएसडीओसी विशेषज्ञों के लिए वहां) है: क्या @method के बिना उपयोगी दस्तावेज (यानि सूचीबद्ध वर्ग के तरीकों के साथ) उत्पन्न करने का कोई तरीका है? या यदि @method वास्तव में आवश्यक है, तो क्या कोई JSDoc जनरेटर है जो फ़ंक्शन नाम से विधि नाम का अनुमान लगा सकता है, ताकि मैं @method addFive के बजाय @method से दूर हो सकूं?

पीएस यदि कोई "आप इसे गलत कर रहे हैं" - टाइप उत्तर जो सीधे प्रश्न का उत्तर नहीं देता है लेकिन समस्या को पूरी तरह से टालने का एक तरीका सुझाता है, मुझे यह सुनना अच्छा लगेगा; मैं निश्चित रूप से कोई JSDoc विशेषज्ञ नहीं हूँ।

Answer 1

आपका सहकर्मी सख्ती से सही नहीं है।

@methodJSDoc3 एक्सटेंशन है जो @function का समानार्थी है, जो defined here है।

उन दस्तावेज़ों की रूपरेखा के रूप में, आपको केवल @functionबल JSDoc को चर के रूप में एक चर के रूप में पहचानने की आवश्यकता है। इस का एक उदाहरण होगा:

/** 
* @function 
*/ 
var func = functionGenerator.generate(); 

एक वस्तु दृष्टिकोण से, आप जब भी आप (एक गैर स्पष्ट रास्ते में एक वस्तु सदस्य के लिए एक समारोह वस्तु आवंटित द्वारा 'गैर स्पष्ट' भी ऐसा ही करना चाहते हैं , मेरा मतलब स्थिर विश्लेषण के संदर्भ में है, यानी यदि आप फ़ंक्शन अभिव्यक्ति का उपयोग नहीं कर रहे हैं)।

तो,

var ageGetter = function() { 
    console.log("A lady never tells"); 
} 

var Person = { 

    name: "Gertrude", 

    getAge: ageGetter 

    getName: function() { 
    return this.name; 
    } 
} 

की तरह कुछ getAge के लिए @method या @function की स्पष्ट उपयोग की आवश्यकता होगी, लेकिन getName के लिए नहीं।

अंतिम बिंदु: आप स्पष्ट रूप से @method नाम शामिल करने के लिए की जरूरत नहीं है जब तक कि वह भी असंभव अनुमान लगाने के लिए (जो बिंदु पर, तो आप शायद कुछ बहुत अजीब इन्स्टेन्शियशन कर रहे है तो शायद भरोसा करने के लिए नहीं कर पाए हैं वैसे भी ऑटो डॉक्टर-पीढ़ी पर)।

Answer 2

मैं यहां गलत हो सकता हूं लेकिन जावास्क्रिप्ट में चीजों को परिभाषित करने के कई तरीकों के कारण आपको कुछ परिभाषाओं के लिए @method की आवश्यकता है।

// JSDoc will recognize this as an object member 
var obj = { 
    mymethod: function() {} 
}; 

// There is no way for JSDoc to tell where my method is going to end up 
var mymethod = function() {}; 
obj.mymethod = mymethod;