// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}
लेकिन मैं कैसे वर्णन करता हूं कि पैरामीटर ऑब्जेक्ट को कैसे संरचित किया जाना चाहिए? उदाहरण के लिए यह कुछ इस तरह होना चाहिए:
{
setting1 : 123, // (required, integer)
setting2 : 'asdf' // (optional, string)
}
जवाबों:
से @param विकि पृष्ठ :
यदि किसी पैरामीटर के पास एक विशेष संपत्ति होने की उम्मीद है, तो आप उस पैरामीटर के लिए @param टैग के तुरंत बाद दस्तावेज कर सकते हैं, जैसे:
/**
* @param userInfo Information about the user.
* @param userInfo.name The name of the user.
* @param userInfo.email The email of the user.
*/
function logIn(userInfo) {
doLogIn(userInfo.name, userInfo.email);
}
पहले एक @config टैग हुआ करता था, जो तत्क्षण @param का अनुसरण करता था, लेकिन ऐसा प्रतीत होता है कि उसे यहाँ पदावनत कर दिया गया ( उदाहरण के लिए )।
actionनाम नहीं है , मैं `foo = ({arg1, arg2, arg2}) => {...}` लिखता हूं। संपादित करें: यहां सवाल stackoverflow.com/questions/36916790/…
अब तक वस्तुओं को मापदंडों / प्रकारों के रूप में दस्तावेज करने के 4 अलग-अलग तरीके हैं। प्रत्येक का अपना उपयोग है। उनमें से केवल 3 का उपयोग रिटर्न वैल्यूज को दस्तावेज करने के लिए किया जा सकता है, हालांकि।
गुणों के ज्ञात सेट के साथ वस्तुओं के लिए (वेरिएंट ए)
/**
* @param {{a: number, b: string, c}} myObj description
*/
यह वाक्यविन्यास उन वस्तुओं के लिए आदर्श है जो केवल इस फ़ंक्शन के मापदंडों के रूप में उपयोग की जाती हैं और प्रत्येक संपत्ति के आगे विवरण की आवश्यकता नहीं होती है। यह के लिए इस्तेमाल किया जा सकता @returnsके रूप में अच्छी तरह से ।
गुणों के ज्ञात सेट के साथ वस्तुओं के लिए (वेरिएंट बी)
गुण सिंटैक्स वाले पैरामीटर बहुत उपयोगी हैं :
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
यह वाक्यविन्यास उन वस्तुओं के लिए आदर्श है जो केवल इस फ़ंक्शन के मापदंडों के रूप में उपयोग की जाती हैं और जिन्हें प्रत्येक संपत्ति के आगे विवरण की आवश्यकता होती है। इसके लिए इस्तेमाल नहीं किया जा सकता है @returns।
उन वस्तुओं के लिए जिनका उपयोग स्रोत में एक से अधिक बिंदुओं पर किया जाएगा
इस मामले में एक @typedef बहुत काम आती है। आप अपने स्रोत में एक बिंदु पर प्रकार को परिभाषित और के लिए एक प्रकार के रूप में उपयोग कर सकते हैं @paramया @returnsया अन्य JSDoc टैग है कि एक प्रकार का उपयोग कर सकते हैं।
/**
* @typedef {Object} Person
* @property {string} name how the person is called
* @property {number} age how many years the person lived
*/
आप इसे एक @paramटैग में उपयोग कर सकते हैं :
/**
* @param {Person} p - Description of p
*/
या एक में @returns:
/**
* @returns {Person} Description
*/
उन वस्तुओं के लिए जिनके मूल्य समान हैं
/**
* @param {Object.<string, number>} dict
*/
पहला प्रकार (स्ट्रिंग) दस्तावेज़ों की कुंजी का प्रकार है जो जावास्क्रिप्ट में हमेशा एक स्ट्रिंग है या कम से कम हमेशा एक स्ट्रिंग के लिए मजबूर किया जाएगा। दूसरा प्रकार (संख्या) मूल्य का प्रकार है; यह किसी भी प्रकार का हो सकता है। इस वाक्यविन्यास का उपयोग भी किया जा सकता है @returns।
साधन
दस्तावेज़ प्रकारों के बारे में उपयोगी जानकारी यहाँ मिल सकती है:
https://jsdoc.app/tags-type.html
पुनश्च:
एक वैकल्पिक मूल्य का उपयोग करने के लिए जो आप उपयोग कर सकते हैं []:
/**
* @param {number} [opt_number] this number is optional
*/
या:
/**
* @param {number|undefined} opt_number this number is optional
*/
{{dir: A|B|C }}?
{[myVariable]: string}
मैं देखता हूं कि @return टैग के बारे में पहले से ही एक उत्तर है, लेकिन मैं इसके बारे में अधिक जानकारी देना चाहता हूं।
सबसे पहले, आधिकारिक JSDoc 3 प्रलेखन हमें कस्टम ऑब्जेक्ट के लिए @ ग्रेट के बारे में कोई उदाहरण नहीं देता है। कृपया https://jsdoc.app/tags-returns.html देखें । अब, देखते हैं कि जब तक कुछ मानक दिखाई नहीं देंगे तब तक हम क्या कर सकते हैं।
फ़ंक्शन रिटर्न ऑब्जेक्ट जहां चाबियाँ गतिशील रूप से उत्पन्न होती हैं। उदाहरण: {1: 'Pete', 2: 'Mary', 3: 'John'}। आमतौर पर, हम इस वस्तु की सहायता से पुनरावृति करते हैं for(var key in obj){...}।
Https://google.github.io/styleguide/javascriptguide.xml#JsTypes के अनुसार संभावित JSDoc
/**
* @return {Object.<number, string>}
*/
function getTmpObject() {
var result = {}
for (var i = 10; i >= 0; i--) {
result[i * 3] = 'someValue' + i;
}
return result
}फ़ंक्शन रिटर्न ऑब्जेक्ट जहां कुंजियाँ ज्ञात स्थिरांक हैं। उदाहरण: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}। हम आसानी से इस वस्तु के गुणों का उपयोग कर सकते हैं object.id:।
Https://groups.google.com/forum/# .topic/jsdoc-users/TMvUedK9tC4 के अनुसार संभावित JSDoc
यह नकली है।
/**
* Generate a point.
*
* @returns {Object} point - The point generated by the factory.
* @returns {number} point.x - The x coordinate.
* @returns {number} point.y - The y coordinate.
*/
var pointFactory = function (x, y) {
return {
x:x,
y:y
}
}पूर्ण मोंटी।
/**
@class generatedPoint
@private
@type {Object}
@property {number} x The x coordinate.
@property {number} y The y coordinate.
*/
function generatedPoint(x, y) {
return {
x:x,
y:y
};
}
/**
* Generate a point.
*
* @returns {generatedPoint} The point generated by the factory.
*/
var pointFactory = function (x, y) {
return new generatedPoint(x, y);
}एक प्रकार परिभाषित करें।
/**
@typedef generatedPoint
@type {Object}
@property {number} x The x coordinate.
@property {number} y The y coordinate.
*/
/**
* Generate a point.
*
* @returns {generatedPoint} The point generated by the factory.
*/
var pointFactory = function (x, y) {
return {
x:x,
y:y
}
}Https://google.github.io/styleguide/javascriptguide.xml#JsTypes के अनुसार
रिकॉर्ड प्रकार।
/**
* @return {{myNum: number, myObject}}
* An anonymous type with the given type members.
*/
function getTmpObject() {
return {
myNum: 2,
myObject: 0 || undefined || {}
}
}के लिए @returnटैग उपयोग {{field1: Number, field2: String}}, देखें: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc
यदि किसी पैरामीटर के पास विशिष्ट संपत्ति होने की उम्मीद है, तो आप अतिरिक्त @param टैग प्रदान करके उस संपत्ति का दस्तावेज कर सकते हैं। उदाहरण के लिए, यदि किसी कर्मचारी पैरामीटर में नाम और विभाग के गुण होने की उम्मीद है, तो आप इसे निम्नानुसार दस्तावेज कर सकते हैं:
/**
* Assign the project to a list of employees.
* @param {Object[]} employees - The employees who are responsible for the project.
* @param {string} employees[].name - The name of an employee.
* @param {string} employees[].department - The employee's department.
*/
function(employees) {
// ...
}यदि कोई पैरामीटर स्पष्ट नाम के बिना नष्ट हो जाता है, तो आप ऑब्जेक्ट को एक उपयुक्त दे सकते हैं और इसके गुणों को दस्तावेज कर सकते हैं।
/**
* Assign the project to an employee.
* @param {Object} employee - The employee who is responsible for the project.
* @param {string} employee.name - The name of the employee.
* @param {string} employee.department - The employee's department.
*/
Project.prototype.assign = function({ name, department }) {
// ...
};स्रोत: JSDoc
@configइन मामलों के लिए एक नया टैग है। वे पूर्ववर्ती से जोड़ते हैं @param।
/** My function does X and Y.
@params {object} parameters An object containing the parameters
@config {integer} setting1 A required setting.
@config {string} [setting2] An optional setting.
@params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
// ...
};
/**
* This callback is displayed as part of the MyClass class.
* @callback MyClass~FuncCallback
* @param {number} responseCode
* @param {string} responseMessage
*/@configटैग के लिए दस्तावेज़ को इंगित कर सकते हैं ? मुझे usejsdoc.org पर कुछ भी नहीं मिला , और यह पृष्ठ बताता @configहै कि पदावनत कर दिया गया है।
@configहै कि इस बिंदु पर पदावनत किया गया है। YUIDoc @attributeइसके बजाय उपयोग करने की सलाह देता है ।