मेरे पास कुछ कोड है जो एक वादा वस्तु लौटाता है, जैसे कि NodeJS के लिए Q लाइब्रेरी का उपयोग करना।
var Q = require('q');
/**
* @returns ???
*/
function task(err) {
return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}
JSDoc का उपयोग करके इस तरह के रिटर्न वैल्यू का दस्तावेज़ीकरण कैसे करें?
@returns {ErrorObject|ResultObject}मदद करता है? टाइप विवरण में "पाइप" साइन का उपयोग करना एक आम बात है।
जवाबों:
यहां तक कि अगर वे जावास्क्रिप्ट में मौजूद नहीं हैं, तो मैंने पाया कि JSdoc "सामान्य प्रकार" को समझता है।
तो आप अपने कस्टम प्रकारों को परिभाषित कर सकते हैं और फिर उपयोग कर सकते हैं /* @return Promise<MyType> */। डॉक में अपने कस्टम Tokenप्रकार के लिंक के साथ एक अच्छा टोकनकेन्यूम (टोकन) → {वादा। <टोकनन}} में निम्नलिखित परिणाम ।
/**
* @typedef Token
* @property {bool} valid True if the token is valid.
* @property {string} id The user id bound to the token.
*/
/**
* Consume a token
* @param {string} token [description]
* @return {Promise<Token>} A promise to the token.
*/
TokenConsume = function (string) {
// bla bla
}
यह /* @return Promise<MyType|Error> */या के साथ भी काम करता है /* @return Promise<MyType, Error> */।
@return {Promise|Token}
@returns {Promise<ForumPost>|Promise<false>|Error}
मैं वादा के लिए एक बाहरी प्रकार को परिभाषित करता हूं:
/**
* A promise object provided by the q promise library.
* @external Promise
* @see {@link https://github.com/kriskowal/q/wiki/API-Reference}
*/
अब आप @returnअपने फ़ंक्शन प्रलेखन के विवरण में वर्णन कर सकते हैं कि क्या होता है वादा:
/**
* @return {external:Promise} On success the promise will be resolved with
* "some result".<br>
* On error the promise will be rejected with an {@link Error}.
*/
function task(err) {
return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}
JSDoc से आप कस्टम टाइप का उपयोग करके भी बना सकते हैं @typedef। मैं इसे थोड़ा बहुत प्रॉप्स / परम का उपयोग करता हूं जो तार के विवरण या सरणियों के प्रकार के विवरण से लिंक करते हैं (जैसे कि stringमैंने एक टाइपराइफ़ बनाया है जिसमें स्ट्रिंग के लिए उपलब्ध मूल निवासी शामिल हैं (नीचे उदाहरण JSDoc देखें) आप एक कस्टम प्रकार परिभाषित कर सकते हैं। इसी तरह से। यह इसलिए है क्योंकि आप रिटर्न के लिए ऑब्जेक्ट डॉट नोटेशन का उपयोग नहीं कर सकते हैं, जैसे आप रिटर्न में क्या है, इसे दर्शाने के लिए @property कर सकते हैं। इसलिए ऐसे मामलों में जहां आप ऑब्जेक्ट की तरह कुछ वापस कर रहे हैं, आप एक परिभाषा बना सकते हैं। उस प्रकार के लिए (' @typedef MyObject) और फिर @returns {myObject} Definition of myObject।
मैं इसके साथ पागल नहीं होऊंगा, हालांकि, क्योंकि प्रकार यथासंभव शाब्दिक होने चाहिए और आप अपने प्रकारों को प्रदूषित नहीं करना चाहते हैं, लेकिन ऐसे मामले हैं जहां आप प्रकार को स्पष्ट रूप से परिभाषित करना चाहते हैं, और इसलिए आप क्या दस्तावेज कर सकते हैं इसमें (एक अच्छा उदाहरण मॉडर्निज़्र है ... यह एक वस्तु लौटाता है, लेकिन आपके पास इसका कोई दस्तावेज़ीकरण नहीं है, इसलिए एक कस्टम टाइपफ़ाइफ़ बनाएं जो विवरण देता है कि उस रिटर्न में क्या है)।
यदि आपको उस मार्ग पर जाने की आवश्यकता नहीं है, तो जैसा कि किसी ने पहले ही उल्लेख किया है, आप पाइप का उपयोग करके किसी भी @param, @property, या @return के लिए कई प्रकार निर्दिष्ट कर सकते हैं |।
आपके मामले में, आप भी एक दस्तावेज़ चाहिए @throws, क्योंकि आप एक फेंक रहे हैं new error: * @throws {error} Throws a true new error event when the property err is undefined or not available।
//saved in a file named typedefs.jsdoc, that is in your jsdoc crawl path
/**
* @typedef string
* @author me
* @description A string literal takes form in a sequence of any valid characters. The `string` type is not the same as `string object`.
* @property {number} length The length of the string
* @property {number} indexOf The occurence (number of characters in from the start of the string) where a specifc character occurs
* @property {number} lastIndexOf The last occurence (number of characters in from the end of the string) where a specifc character occurs
* @property {string|number} charAt Gives the character that occurs in a specific part of the string
* @property {array} split Allows a string to be split on characters, such as `myString.split(' ')` will split the string into an array on blank spaces
* @property {string} toLowerCase Transfer a string to be all lower case
* @property {string} toUpperCase Transfer a string to be all upper case
* @property {string} substring Used to take a part of a string from a given range, such as `myString.substring(0,5)` will return the first 6 characters
* @property {string} substr Simialr to `substring`, `substr` uses a starting point, and then the number of characters to continue the range. `mystring.substr(2,8)` will return the characters starting at character 2 and conitnuing on for 8 more characters
* @example var myString = 'this is my string, there are many like it but this one is HOT!';
* @example
//This example uses the string object to create a string...this is almost never needed
myString = new String('my string');
myEasierString = 'my string';//exactly the same as what the line above is doing
*/
@typedefटैग के प्रकार को अनसुलझे के रूप में हाइलाइट करता है । हाँ, ओह, मैं इसे यहाँ
सिंटेक्स वर्तमान में Jsdoc3 द्वारा समर्थित है:
/**
* Retrieve the user's favorite color.
*
* @returns {Promise<string>} A promise that contains the user's favorite color
* when fulfilled.
*/
User.prototype.getFavoriteColor = function() {
// ...
};
भविष्य में समर्थित?
/**
* A promise for the user's favorite color.
*
* @promise FavoriteColorPromise
* @fulfill {string} The user's favorite color.
* @reject {TypeError} The user's favorite color is an invalid type.
* @reject {MissingColorError} The user has not specified a favorite color.
*/
/**
* Retrieve the user's favorite color.
*
* @returns {FavoriteColorPromise} A promise for the user's favorite color.
*/
User.prototype.getFavoriteColor = function() {
// ...
};
Github चर्चा यहां देखें: https://github.com/jsdoc3/jsdoc/issues/1197
ऐसा करने का एक और तरीका भी है, भले ही यह विकृत हो सकता है । जब कोई कहता है कि यह पदावनत (उस उत्तर के लिए टिप्पणियों की जाँच करें) पर जोर दे सकता है, जबकि अन्य कहते हैं कि दोनों में से कोई एक ठीक है। मैं इसे पूर्णता के लिए वैसे भी रिपोर्ट कर रहा हूं।
अब, Promise.all()उदाहरण के लिए लें जो एक सरणी के साथ पूरा किया गया एक वादा लौटाता है। डॉट नोटेशन शैली के साथ यह नीचे दिखाए गए जैसा दिखेगा:
{Promise.<Array.<*>>}
यह JetBrains उत्पादों (जैसे PhpStorm, WebStorm) पर काम करता है और इसका उपयोग jsforce डॉक्स में भी किया जाता है ।
लेखन के समय जब मैं PHPStorm के साथ कुछ डॉक्स को ऑटो-जनरेट करने की कोशिश करता हूं तो यह इस शैली के लिए डिफॉल्ट करता है जबकि मुझे इसका खराब संदर्भ मिला।
वैसे भी यदि आप एक उदाहरण के रूप में निम्नलिखित कार्य करते हैं:
// NOTE: async functions always return a Promise
const test = async () => {
let array1 = [], array2 = [];
return {array1, array2};
};
जब मैंने PhpStorm को डॉक्स उत्पन्न करने दिया तो मुझे यह मिल गया:
/**
* @returns {Promise.<{array1: Array, array2: Array}>}
*/
const test = async () => {
let array1 = [], array2 = [];
return {array1, array2};
};
यहाँ है कि मुझे क्या करना पसंद है (जो थोड़ा अधिक हो सकता है):
/**
* @external Promise
* @see {@link http://api.jquery.com/Types/#Promise Promise}
*/
/**
* This callback is called when the result is loaded.
*
* @callback SuccessCallback
* @param {string} result - The result is loaded.
*/
/**
* This callback is called when the result fails to load.
*
* @callback ErrorCallback
* @param {Error} error - The error that occurred while loading the result.
*/
/**
* Resolves with a {@link SuccessCallback}, fails with a {@link ErrorCallback}
*
* @typedef {external:Promise} LoadResultPromise
*/
/**
* Loads the result
*
* @returns {LoadResultPromise} The promise that the result will load.
*/
function loadResult() {
// do something
return promise;
}
मूल रूप से, कुछ दस्तावेज़ के लिंक के साथ आधार वादा को परिभाषित करें (इस मामले में मैं jQuery के एक से लिंक कर रहा हूं), अपने कॉलबैक को परिभाषित करें जिसे तब कॉल किया जाएगा जब वादा या तो हल हो जाता है या विफल हो जाता है, फिर अपने विशिष्ट वादे को परिभाषित करें जो लिंक से वापस जुड़ता है कॉलबैक प्रलेखन।
अंत में, रिटर्न प्रकार के रूप में अपने विशिष्ट वादे प्रकार का उपयोग करें।