ज्ञात पैरामीटर प्रकारों के साथ एक चर लंबाई के साथ एक तर्क सूची दस्तावेज़ कैसे दस्तावेज़?

Question

संबंधित: Correct way to document open-ended argument functions in JSDoc

मैं एक समारोह है कि arguments चर तक पहुँचने के द्वारा कई सरणियों को स्वीकार करता है:

/** 
* @param options An object containing options 
* @param [options.bind] blablabla (optional) 
*/ 
function modify_function (options) { 
    for (var i=1; i<arguments.length; i++) { 
     // ... 
    } 
} 

अब, मुझे पता है कि options के अलावा प्रत्येक तर्क मान जो लायक कुछ दस्तावेज़ीकृत हैं युक्त एक सरणी है:

[search_term, replacement, options] 

मैं चर पैरामीटर लाइन में (लंबा) विवरण डाल पर विचार नहीं कर रहा हूँ।

@param {...} खोज शब्द, प्रतिस्थापन और उसके विकल्पों के साथ एक सरणी; सूचकांक 0: फ़ंक्शन के भीतर खोज शब्द; 1: प्रतिस्थापन पाठ; 2: वैकल्पिक विकल्प (catch_errors: त्रुटियों को पकड़ता है और इसे लॉग करता है, बचें: प्रतिस्थापन टेक्स्ट में डॉलर से बचें, pos: खोज शब्द से पहले प्रतिस्थापन रखने के लिए "एल", इसे बाद में रखने के लिए "आर") एक पठनीय समाधान नहीं है और प्रकार दिखाई नहीं दे रहा है।

क्या एक चर पैरामीटर के प्रकारों और मानों को दस्तावेज करने का कोई तरीका है?

@param {...[]} An array with search terms, replacements and its options 
@param {...[0]} The search term within the function 
@param {...[1]} The replacement text 
@param {...[2]} An optional object with obtions for the replacement 
@param {...[2].catch_errors} catches errors and log it 
@param {...[2].escape} etc... 

ऊपर बदसूरत लग रहा है, लेकिन यह आपको मैं क्या हासिल करने की कोशिश कर रहा हूँ की एक विचार देना चाहिए:

• दस्तावेज़ एक चर पैरामीटर के प्रकार (इस मामले में किसी सरणी)
• दस्तावेज़ इस सरणी
• दस्तावेज़ उपयोग इस सरणी

आलस्य के लिए अंदर एक वस्तु का गुण, मैंने के मूल्यों एक वस्तु के बजाय एक सरणी। अन्य सुझाव हमेशा स्वागत है।

Answer 1

उदाहरण के लिए आपका फ़ंक्शन वास्तव में परिवर्तनीय तर्क नहीं है, आपको केवल उस हस्ताक्षर को बदलना चाहिए जो मिलेमा ने सुझाया था।सिवाय इसके कि JSDoc एक छोटे से foundrama की तुलना में बेहतर सिंटैक्स है, सुझाव दिया

/** 
* @param {String} searchTerm 
* @param {String} replacementText 
* @param {Object} opts (optional) An object containing the replacement options 
* @param {Function} opts.catch_errors Description text 
* @param {Event} opts.catch_errors.e The name of the first parameter 
*   passed to catch_errors 
* @param {Type} opts.escape Description of options 
*/ 

और आप इसे

modify_text('search', 'replacement', { 
    catch_errors: function(e) { 

    }, 
    escape: 'someEscape' 

}); 

तुम सच में varargs शैली के लिए एक मामला है तो तरह फोन चाहते हैं, इसके बारे में एक चर होना चाहिए एक ही प्रकार के पैरामीटर सूची के अंत में पारित किया जा सकता है कि, मैं इसे निम्नलिखित की तरह दस्तावेज़, हालांकि यह एक JSDoc मानक नहीं है, यह क्या गूगल अपनी दस्तावेज़ीकरण

/** 
* Sums its parameters 
* @param {...number} var_args Numbers to be added together 
* @return number 
*/ 
function sum(/* num, num, ... */) { 
    var sum = 0; 
    for (var i =0; i < arguments.length; i++) { 
     sum += arguments[i]; 
    } 
    return sum; 
} 

Answer 2

जब तक कि आप किसी अन्य एपीआई द्वारा प्रतिबंधित नहीं होते हैं, तो पहली बात यह है कि मैं सुझाव दूंगा: किसी डेटा संग्रह को छोड़कर किसी भी चीज के लिए किसी सरणी का उपयोग न करें जिसे आप फिर से शुरू करना चाहते हैं।

शायद सबसे अच्छा तरीका यहां फ़ंक्शन को पुन: कारक करना होगा जैसे कि यह तीन पैरामीटर या किसी अन्य प्रकार की परम वस्तु लेता है।

/** 
* @param {String} searchTerm 
* @param {String} replacementText 
* @param {Object} replacementOpts (optional) An object containing the replacement 
* options; optional values in the object include:<ul> 
    <li>catch_errors {Type} description text...</li> 
    <li>escape {Type} description text...</li></ul> 
*/ 

मैं दृढ़ता से (फिर से: "जब तक आप अपने नियंत्रण से बाहर कुछ एपीआई से घिरा रहे हैं) सरणी का उपयोग कर के खिलाफ सलाह देते हैं:। के रूप में यह दोनों भंगुर और अंत में एक छोटे से भ्रामक साबित होगा