JSDoc: रिटर्न ऑब्जेक्ट संरचना

Question

मैं JSDoc को किसी ऑब्जेक्ट की संरचना के बारे में कैसे बता सकता हूं जो वापस आ गया है। मैंने @return {{field1: type, field2: type, ...}} descriptionसिंटैक्स पाया है और इसे आजमाया है:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {{x: Number, y: Number}} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}

हालांकि यह सफलतापूर्वक सफल होता है, परिणामी प्रलेखन केवल यह बताता है:

Returns: 
    The location of an event
    Type: Object

मैं एक एपीआई विकसित कर रहा हूं और लोगों को उस वस्तु के बारे में जानने की जरूरत है जो उन्हें वापस मिल जाएगी। क्या JSDoc में यह संभव है? मैं JSDoc3.3.0-beta1 का उपयोग कर रहा हूं।

Comments

मुझे पता है कि @typedefयह एक समाधान / समाधान है, लेकिन इसके लिए अजीब लगता है कि यह शाब्दिक वस्तुओं के साथ काम नहीं करता है। यदि कोई भविष्य में इस पर ठोकर खाता है (जैसा कि मैंने किया था) मैंने एक मुद्दा जोड़ दिया है github.com/jsdoc/jsdoc/issues/1678 जो इस पृष्ठ से अधिक जानकारी रख सकता है।

— लेस्ज़ेक

Answer 1

एक @typdef का उपयोग करके अपनी संरचना को अलग से परिभाषित करें :

/**
 * @typedef {Object} Point
 * @property {number} x - The X Coordinate
 * @property {number} y - The Y Coordinate
 */

और इसे रिटर्न प्रकार के रूप में उपयोग करें:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {Point} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}

Comments

धन्यवाद। एकाधिक @returnकथन वास्तव में काम करते हैं, लेकिन वे आउटपुट में सूचीबद्ध होते हैं जैसे कि वे कई रिटर्न थे (एक बुलेट पॉइंट स्टेट्स point - Objectऔर फिर दो अन्य बुलेट पॉइंट्स के लिए ) point.x - Numberऔर point.y - Number। जब तक मैं उसके साथ रह सकता हूं, मुझे लगता है कि लौटी हुई वस्तु का संघनित उत्पादन होने का कोई तरीका नहीं है? या बहुत कम से कम point.xऔर point.yइंडेंट के लिए प्रविष्टियाँ हैं ?

— ब्लैकवॉल्फ

हां, यह सबसे अच्छा विकल्प लगता है। मैंने सोचा कि एक गैर-नाम वापसी इकाई का एक तरीका हो सकता है, लेकिन @typedefप्रलेखन आउटपुट के संदर्भ में दृष्टिकोण सबसे स्पष्ट है, धन्यवाद!

— ब्लैकवॉल्फ

2 विकल्प के रूप में पहला विकल्प हटा दिया गया है।

— BGerrissen

आप बेहतर रूप से जोड़ते हैं @innerया टाइप करते हैं परिभाषा globalमें प्रलेखन में गुंजाइश होगी । +1

— ओनुर येल्ड्रिअम

मैंने हमेशा उपयोग किया है @typedef {Object} Point। वास्तव में, PointPhsStorm में इस दो-लाइन फॉर्म हाइलाइट्स का उपयोग करते हुए संदेश "अनारक्षित चर या टाइप प्वाइंट" के साथ डाला गया है। @typedefडॉक्स इस समर्थन करते हैं, लेकिन मुझे लगता है कि यह एक मान्य संस्करण है इस जवाब संपादित करने के लिए नहीं करना चाहती।

— डेविड हरकनेस

Answer 2

पहले से पोस्ट किए गए सुझावों का एक विकल्प, आप इस प्रारूप का उपयोग कर सकते हैं:

/**
 * Get the connection state.
 *
 * @returns {Object} connection The connection state.
 * @returns {boolean} connection.isConnected Whether the authenticated user is currently connected.
 * @returns {boolean} connection.isPending Whether the authenticated user's connection is currently pending.
 * @returns {Object} connection.error The error object if an error occurred.
 * @returns {string} connection.error.message The error message.
 * @returns {string} connection.error.stack The stack trace of the error.
 */
getConnection () {
  return {
    isConnected: true,
    isPending: false,
    error
  }
}

जो निम्नलिखित प्रलेखन आउटपुट देगा:

    Get the connection state.

    getConnection(): Object

    Returns
    Object: connection The connection state.
    boolean: connection.isConnected Whether the authenticated user is currently connected.
    boolean: connection.isPending Whether the authenticated users connection is currently pending.
    Object: connection.error The error object if an error occurred.
    string: connection.error.message The error message.
    string: connection.error.stack The stack trace of the error.

Answer 3

एक साफ समाधान के लिए एक वर्ग लिखना है और उसे वापस करना है।

/** 
 *  @class Point
 *  @type {Object}
 *  @property {number} x The X-coordinate.
 *  @property {number} y The Y-coordinate.
 */
function Point(x, y) {
  return {
        x: x,
        y: y
    };
}

/**
 * @returns {Point} The location of the event.
 */
var getEventLocation = function(e, type) {
    ...
    return new Point(x, y);
};

Comments

जब मैं ऐसा करता हूं लेकिन Google क्लोजर कंपाइलर का उपयोग करता हूं, तो मुझे एक चेतावनी मिलती है: "गैर-कंस्ट्रक्टर को तुरंत नहीं कर सकता"। मैंने @constructor को फंक्शन (@return के ऊपर) जोड़ने की कोशिश की, लेकिन इससे कोई फायदा नहीं हुआ। अगर कोई जानता है कि उसे कैसे ठीक करना है, तो कृपया मुझे बताएं। धन्यवाद!

— AndroidDev

@AndroidDev इसका कारण यह है कि फ़ंक्शन Pointएक कंस्ट्रक्टर नहीं है, जो कि Pointफ़ंक्शन के शरीर को बदलने के लिएthis.x = x; this.y = y;

— Feirell

मुझे वह कारण नहीं दिखाई देता है कि हमें यहां नए प्रयोग करने की आवश्यकता है, बस प्वाइंट (x, y) क्यों नहीं लौटाएं?

— CHANist

@ इतिहासकार, newवाक्य रचना से एक उदाहरण बनाना है constructor। इसके बिना new, thisवैश्विक संदर्भ होगा। आप newप्रभाव को देखने के बिना एक उदाहरण बनाने की कोशिश कर सकते हैं।

— आकाश