जावास्क्रिप्ट में वापसी दस्तावेज कैसे करें

Question

मैं ब्राउज़र एप्लिकेशन के लिए काम पर परियोजना के लिए अपनी खुद की लाइब्रेरी लिख रहा हूं और मुझे कोड की टिप्पणी करने का निर्णय लेने में वही पुरानी समस्या है।

मैं JsDoc वाक्यविन्यास का पालन करने की कोशिश कर रहा हूं, लेकिन शायद Google Closure Compiler तरीका जारी रखेगा। पोर्टेबिलिटी के लिए केवल दो @return और @returns टैग का उपयोग कर समाप्त हो सकता है, केवल पोर्टेबिलिटी के लिए (जब मैं प्रलेखन की ऑटो-पीढ़ी सेट करता हूं)।

अब, प्रश्न, आप किसी फ़ंक्शन से कस्टम अज्ञात ऑब्जेक्ट की वापसी कैसे दस्तावेज़ करते हैं? उदाहरण के लिए:

return { 
    username: 'username', 
    password: 'password', 
    enabled: true 
}; 

JsDoc कैसे एक @param कुछ क्षेत्रों के साथ वस्तु की उम्मीद प्रलेखित किया जा सकता है, लेकिन नहीं @returns का उदाहरण दिया गया है। इसी प्रकार, एक रिकॉर्ड प्रकार का Google क्लोजर कंपाइलर दस्तावेज अस्पष्ट है और इसका काम करने के लिए कोई उदाहरण नहीं है।

Answer 1

तो समारोह

function myFunction() { 
    /** 
    * Description of my function 
    * @return {!Object.<string, string|boolean>} Returns an object containing username, password and enabled information 
    */ 

    // Do stuff 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
    } 
} 

Answer 2

बंद-संकलक के शीर्ष में रखते JSDoc annotations के एक सबसेट का उपयोग करता है (और अपनी खुद की कुछ कहते हैं)। पूर्ण सेट के लिए annotation reference for the compiler देखें। एक जेएसडीओसी एनोटेशन जावाडॉक एनोटेशन के समान है और एक टिप्पणी ब्लॉक है जो /** (दो सितारों) से शुरू होता है। हालांकि टिप्पणी की प्रत्येक पंक्ति अक्सर अपने * के साथ शुरू होती है, यह एक ऐसा सम्मेलन है जिसकी आवश्यकता नहीं है। प्रति पंक्ति केवल एक JSDoc टैग की अनुमति है, लेकिन टैग के लिए तर्क कई पंक्तियों का विस्तार कर सकते हैं।

एनोटेशन आमतौर पर निम्नलिखित कथन पर लागू होता है। यहाँ कुछ उदाहरण हैं:

चर

/** @type {string} */ var a; 

प्रकार कास्ट

var b = /** @type {string} */ (window['foo']); 

टिप्पणी अतिरिक्त कोष्ठक

नाम समारोह

/** 
* @param {string} bar 
* @return {boolean} 
*/ 
function foo(bar) { return true; } 

फंक्शन (यूनियनों, और रिकॉर्ड प्रकार सहित)

/** @type {function(string):boolean} */ 
var foo = function(bar) { return true; } 

var foo2 = 
    /** 
    * @param {string} bar 
    * @return {boolean} 
    */ 
    function(bar) { return true; } 

typedef

परिसर प्रकार सुविधा और रख-रखाव के लिए एक typedef प्रयोग करने के लिए किया जा सकता है एलियास भाव। ये एनोटेशन लंबे हो सकते हैं, लेकिन पठनीयता के लिए कई लाइनों पर विभाजित किया जा सकता है।

/** @typedef {{ 
*    foo:string, 
*    bar:number, 
*    foobar:number|string 
*   }} 
*/ 
var mytype; 

आपके मूल उदाहरण के लिए, ऐसे फ़ंक्शन रिटर्न मान को एनोटेट करने के कई संभावित तरीके हैं।

/** @return {{username:string, password:string, enabled:boolean}} */ 
function() { 
    return { 
    username: 'username', 
    password: 'password', 
    enabled: true 
    } 
} 

नोट अतिरिक्त {}: सबसे विशिष्ट और अभी भी सुविधाजनक में से एक रिकॉर्ड प्रकार है। यह भी ध्यान रखें कि रिकॉर्ड प्रकार संपत्ति नामकरण को रोक नहीं पाएंगे।

यह एनोटेशन संकलक को बताता है कि फ़ंक्शन username, password और enabled गुणों के साथ एक अज्ञात प्रकार देता है। अन्य वैध विकल्प कहीं और एक इंटरफ़ेस को परिभाषित करना होगा और उस इंटरफ़ेस होने के लिए वापसी मान टाइप करना होगा। कम से कम विशिष्ट एनोटेशन Object या * होगा।

संभावित एनोटेशन की विस्तृत श्रृंखला देखने के लिए, extern files in the Compiler project पर एक नज़र डालें।

Answer 3

ऐसा करने के लिए अच्छे और पोर्टेबल तरीकों में से एक कीवर्ड के रूप में वापसी का उपयोग करके निम्न की तरह है। https://github.com/senchalabs/jsduck/wiki/%40return

/** 
* @return {object} return An object with the following properties 
* @return {string} return.username Some username 
* @return {string} return.password Some password 
* @return {boolean} return.enabled Is the user enabled? 
*/ 
function getObj() { 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
     }; 
} 

आप को कई जगहों पर इसका इस्तेमाल करने की है, तो आप इसकी नक़ल करने के लिए होता है, या @typedef उपयोग करते हैं, लेकिन मैं समझ नहीं किया है @typedef के लिए टिप्पणी जोड़ने के लिए कैसे तो मैं निम्नलिखित

की तरह कुछ का उपयोग

/** 
* @typedef {username:string, password:string, enabled:boolean} MyType 
* 
* username: The name of the user 
* password: Some password 
* enabled: Is the user enabled? 
*/ 

/** 
* @return {MyType} 
*/ 
function getObj() { 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
     }; 
} 

तुम भी सुझाव कोशिश कर सकते हैं यहाँ How can I document a type in webstorm using just jsdoc?