सवाल Jsdoc के साथ अनाम वस्तुओं और कार्यों को दस्तावेज करने का सबसे अच्छा तरीका [बंद]


संपादित करें: यह तकनीकी रूप से 2 भाग प्रश्न है। मैंने सबसे अच्छा जवाब चुना है जो सामान्य रूप से प्रश्न को कवर करता है और विशिष्ट प्रश्न को संभालने वाले उत्तर से जुड़ा हुआ है।

Jsdoc के साथ अज्ञात ऑब्जेक्ट्स और फ़ंक्शंस को दस्तावेज़ करने का सबसे अच्छा तरीका क्या है?

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

न तो PageRequest वस्तु या callback कोड में मौजूद है। उन्हें प्रदान किया जाएगा getPage() चलने के समय पर। लेकिन मैं यह निर्धारित करने में सक्षम होना चाहता हूं कि ऑब्जेक्ट और फ़ंक्शन क्या हैं।

मैं इसे बनाने के साथ दूर हो सकता है PageRequest दस्तावेज़ को ऑब्जेक्ट करें कि:

/**
 * @namespace {PageRequest} Object specification
 * @property {String} pageId ID of the page you want.
 * @property {String} pageName Name of the page you want.
 */
var PageRequest = {
    pageId : null,
    pageName : null
};

और यह ठीक है (हालांकि मैं ऐसा करने के बेहतर तरीकों के लिए खुला हूं)।

दस्तावेज करने का सबसे अच्छा तरीका क्या है callback समारोह? मैं दस्तावेज़ में इसे जानना चाहता हूं, उदाहरण के लिए, कॉलबैक फ़ंक्शन इस रूप में है:

callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)

कोई जानकारी यह कैसे करनी है?


51
2017-07-03 12:18


मूल




जवाब:


आप उन सामानों को दस्तावेज़ कर सकते हैं जो @name टैग का उपयोग कर कोड में मौजूद नहीं हैं:

        /** Description of the function
            @name IDontReallyExist
            @function
            @param {String} someParameter Description
        */


        /** The CallAgain method calls the provided function twice
            @param {IDontReallyExist} func The function to call twice
        */
        exports.CallAgain = function(func) { func(); func(); }

यहाँ है @name टैग प्रलेखन । आपको मिल सकता है नाम पथ भी उपयोगी


42
2017-08-22 20:44



वास्तव में साफ! कॉलबैक दस्तावेज करने का एक शानदार तरीका है। - oligofren
लेकिन मुझे नहीं लगता कि यह अज्ञात वस्तुओं के लिए कैसे काम करता है? किसी ऑब्जेक्ट को बनाने के लिए कुछ फ़ंक्शन में भेजा गया एक ऑब्जेक्ट ऑब्जेक्ट कहें जो वर्तमान दायरे में दिखाई नहीं दे रहा है। - oligofren
यदि आप इसका उपयोग नहीं करना चाहते हैं @name अपने अज्ञात ऑब्जेक्ट को नाम देने के लिए टैग करें, उस ऑब्जेक्ट का वर्णन करें जहां इसका उपयोग किया गया था, वह होगा @paramअपनी सेटिंग्स ऑब्जेक्ट उदाहरण के लिए टैग का बॉडी। - Eric
वहाँ भी है @callback टैग। - kzh


आप उपयोग कर सकते हैं @callback या @typedef

/**
 * @callback arrayCallback
 * @param  {object} element - Value of array element
 * @param  {number} index   - Index of array element
 * @param  {Array}  array   - Array itself
 */

/**
 * @param {arrayCallback} callback - function applied against elements
 * @return {Array} with elements transformed by callback
 */
Array.prototype.map = function(callback) { ... }

28
2017-07-23 13:10



संदर्भ: usejsdoc.org/tags-callback.html - Chris Moschini
@ChrisMoschini धन्यवाद। @callback उत्तर में टैग उचित दस्तावेज़ीकरण पृष्ठ से जुड़ा हुआ था। - kzh


स्टूडगेक के उत्तर की तारीफ करने के लिए, मैंने एक उदाहरण दिया है जो दिखाता है कि क्या Google क्लोजर कंपाइलर के साथ जेएसडोक आपको करने देता है

ध्यान दें कि प्रलेखित अज्ञात प्रकार जेनरेट किए गए minified फ़ाइल से हटा दिए जाते हैं और संकलक सुनिश्चित करता है कि वैध ऑब्जेक्ट्स (जब संभव हो) पास हो जाएं। हालांकि, भले ही आप कंपाइलर का उपयोग न करें, यह अगले डेवलपर और टूल जैसे वेबस्टॉर्म (इंटेलिजे) को समझने में मदद कर सकता है और आपको कोड पूरा करने देता है।

// This defines an named type that you don't need much besides its name in the code
// Look at the definition of Page#getPage which illustrates defining a type inline
/**  @typedef { pageId : string, pageName : string, contents: string} */
var PageResponse;

/**
 * @class {Page} Page Class specification
 */
var Page = function() {    
    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     *
     * The type for the second parameter for the function below is defined inline
     *
     * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback
     *        Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

8
2018-04-18 16:51



हाय, यह सबसे सुरुचिपूर्ण जवाब लगता है, हालांकि जेएसडीओसी आउटपुट में अभी शामिल है function विशिष्ट पैरामीटर टाइपिंग के बिना। मैं jsdoc का उपयोग कर रहा हूँ 3.4.0। क्या यह वाक्यविन्यास पूरी तरह से समर्थित नहीं है? - Peter V
@PeteV। मैंने जेएसडोक और क्लोजर कंपाइलर के बीच सिंक्रनाइज़ेशन के स्तर के साथ नहीं रखा है। मैं आपको वैकल्पिक दस्तावेज़ जेनरेटर को देखने की सलाह दूंगा जो क्लोजर कंपाइलर के साथ काम करने के लिए बनाए जाते हैं (क्योंकि यह जेएसडोक मानक का सुपरसेट है)। प्रयत्न plovr.com , seehuhn.de/pages/jvjsdoc या github.com/google/closure-compiler/wiki/... । मैं जावास्क्रिप्ट पर स्थैतिक टाइपिंग जोड़ने के लिए टाइपस्क्रिप्ट का उपयोग करने के लिए आगे बढ़ गया हूं - Juan Mendes


@link विधियों और कक्षाओं के लिए इनलाइन लिंक जोड़ सकते हैं।

/**
 * Get a page from the server
 * @param {PageRequest} pageRequest Info on the page you want to request
 * @param {function} callback Function executed when page is retrieved<br />
 * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus)
 */
this.getPage = function (pageRequest, callback) {
};

आदर्श नहीं है, लेकिन यह काम पूरा हो जाता है।


1
2017-07-06 19:07





Google क्लोजर कंपाइलर एनोटेशन में है अभिव्यक्ति टाइप करें इसके लिए जिसमें विशिष्ट तर्क, वापसी प्रकार, और यहां तक ​​कि यह भी इंगित करने की क्षमता शामिल है। कई पुस्तकालय Google क्लोजर कंपाइलर एनोटेशन के बाद देख रहे हैं, क्योंकि वे इसका उपयोग अपने कोड को कम करने के लिए करना चाहते हैं। तो यह कुछ गति है। नकारात्मकता यह है कि मुझे विवरण देने का कोई तरीका नहीं दिख रहा है।

विवरण प्रदान करने के लिए शायद जेएसडीओसी टूलकिट गुणों के साथ पैरामीटर्स दृष्टिकोण काम करेगा (पृष्ठ के नीचे देखें)। यह वही है जो मैं अभी कर रहा हूं। जेएसडीक टूलकिट वी 3 पर काम शुरू करने के लिए तैयार है, इसलिए प्रतिक्रिया अच्छी हो सकती है।


1
2018-02-23 16:22





आप उसी वर्ग के भीतर किसी अन्य विधि से लिंक करने के लिए @see का उपयोग कर सकते हैं। विधि का कभी भी उपयोग नहीं किया जाएगा, यह सिर्फ दस्तावेज़ीकरण उद्देश्यों के लिए होगा।

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     * @see #getPageCallback 
     */
    this.getPage = function (pageRequest, callback) {
    }; 

    /**
     * Called when page request completes 
     * @param {PageResponse} pageResponse The requested page
     * @param {PageRequestStatus} pageRequestStatus Status of the page
     */
    //#ifdef 0
    this.getPageCallback = function (pageResponse, pageRequestStatus) { };
    //#endif 
};

यदि आप किसी प्रकार की बिल्ड सिस्टम का उपयोग कर रहे हैं, तो डमी विधि को आसानी से निर्माण से छोड़ा जा सकता है।


0
2017-07-06 01:33



धन्यवाद, नहीं। मैं वर्तमान में (ifdef के बिना) कर रहा हूं और यह काम करता है, लेकिन मैं चाहता हूं कि उपयोगकर्ता तुरंत यह देखने में सक्षम हो कि यह एक ऐसा फ़ंक्शन है जो एक्स और वाई को बिना छोड़ दिए गए पैरा को स्वीकार करता है। Google मानचित्र एपीआई कैसे करता है इसके समान। उदाहरण: code.google.com/apis/maps/documentation/javascript/... - Josh Johnson
बस पता चला कि @ लिंक जो मैं कर रहा हूं वह कर सकता है। यह सही नहीं है लेकिन यह काम करता है। यदि किसी और को यह उपयोगी लगता है तो मैं एक अलग उत्तर बनाउंगा। - Josh Johnson