YUIDocs

Question

में कक्षाओं और मॉड्यूल का दस्तावेज़ीकरण मुझे समूहित मॉड्यूल के सेट के लिए मेरे दस्तावेज़ लिखने में कुछ परेशानी हो रही है। मुझे लगता है कि यह आंशिक रूप से @class, @module और @namespace पर एक गलत धारणा है। (या हो सकता है कि यह याहू में जेएस में 'शास्त्रीय' भाषा शब्दावली को छेड़छाड़ करने का नतीजा हो।)

मुझे नीचे एक चौंका देने वाला नमूना मिला है जो दिखा रहा है कि मेरा अधिकांश कोड कैसे लिखा गया है और यूयूआईडीओसी में इसे दस्तावेज करने का मेरा प्रयास -अंदाज। पहले दो भाग (Foo और BazManager) बहुत सरल हैं। मेरे लिए:

• Foo@class है;
• Baz@class है;
• BazManager@module (या शायद @class है जिसमें केवल @static सदस्य हैं);
• Qux भी @module है लेकिन इसमें केवल विधियां हैं।

मेरे समस्याएं हैं:

1. हैं BazManager एक @module है, FooBazManager के तहत पता चलता है;
2. यदि BazManager@class है, तो Baz के अंदर विधियों को इसमें शामिल किया जाए यदि आप @for को सब कुछ में नहीं जोड़ते हैं;
3. यदि BazManager@class है, तो Baz की दस्तावेज़ीकरण वास्तव में मुश्किल हो जाती है;
4. मुझे वास्तव में नहीं पता कि मुझे Qux दस्तावेज कैसे करना है। ऐसा लगता है कि मुझे मॉड्यूल होना है, लेकिन चूंकि इसमें @class ईएस नहीं है, इसलिए यह BazManager समेत इसके आसपास सबकुछ घूमता है। तो यह @class होना चाहिए।

क्या कोई सुझाव दे सकता है कि मुझे यह कैसे करना चाहिए? मुझे वास्तव में परवाह नहीं है कि अगर मुझे दस्तावेज में सबकुछ ठीक से उत्पन्न हो जाता है तब तक मुझे सही शर्तें मिलती हैं।

// File: Widgets.js 

/** 
MyNamespace namespace 
@namespace MyNamespace 
*/ 
var MyNamespace = window.MyNamespace || {}; 

//--------------------PART 1: Foo-------------------// 

/** 
This is a description of Foo. 
@class Foo 
*/ 
MyNamespace.Foo = function() { 
    this.toString = function() { 
     return "I am a foo"; 
    }; 

    /** 
    This is Foo's private method description. 
    @method privateMethod 
    @private 
    */ 
    var privateMethod = function() {}; 

    /** 
    This is Foo's public method description. 
    @method publicMethod 
    */ 
    this.publicMethod = function() {}; 
}; 


//--------------------PART 2: Baz-------------------// 
/** 
This is a description of BazManager. 
@module BazManager 
@namespace MyNamespace 
*/ 
MyNamespace.BazManager = (function() { 
    var self = {}; 

    /** 
    This is a description of Baz. 
    @class Baz 
    */ 
    var Baz = function (type) { 
     /** 
     toString description 
     @method toString 
     @returns {String} 
     */ 
     this.toString = function() { 
      return "I am a baz and I'm " + type; 
     }; 
    }; 

    /** 
    This is BazManager's privateBaz description. 
    @method privateBaz 
    @private 
    */ 
    var privateBaz = new Baz("private"); 

    /** 
    This is BazManager's publicBaz description. 
    @method publicBaz 
    */ 
    self.publicBaz = new Baz("public"); 

    return self; 
}()); 


//--------------------PART 3: Qux-------------------// 

MyNamespace.Qux = (function() { 
    var self = {}; 
    /** 
    execute description 
    @method execute 
    @private 
    */ 
    var execute = function() { 
     console.log("Qux is done"); 
    }; 

    /** 
    start description 
    @method start 
    */ 
    self.start = function() { 
     setTimeout(execute, 1000); 
    }; 

    return self; 
}()); 

Answer 1

YUIDoc @class में दोनों शास्त्रीय कक्षाओं के लिए और जिन वस्तुओं पर तरीकों में से एक गुच्छा शामिल के लिए प्रयोग किया जाता है:

यहाँ मेरी नमूना कोड है। जिन वर्गों को तत्काल माना जाता है उन्हें @constructor के साथ भी चिह्नित किया जाता है। यही कारण है कि उन वर्गों को तब टेम्पलेट्स में दिखाया जाता है। कई अकेले कार्यों की तुलना में कक्षा को ट्रैक करना बहुत आसान है।

यूयूआई टीम और समुदाय में कई (स्वयं शामिल) @namespace से दूर जा रहे प्रतीत होते हैं। सही होना मुश्किल है। इसके बजाए हम उनमें से डॉट्स के साथ कक्षा के नाम लिख रहे हैं, यानी: @class Plugin.NodeMenuNav।

मॉड्यूल यूयूआई अर्थ में हैं और इसे ज्यादातर "स्क्रिप्ट" के रूप में समझा जा सकता है जिसमें एक या अधिक कक्षाएं होती हैं।

तो एक विशिष्ट मॉड्यूल इस तरह दिखेगा:

/** 
A series of utilities to do stuff 

@module Stuff 
**/ 

/** 
A class that does foo very well 

@class Foo 
@constructor 
@param {Object} [config] Configuration object 
@param {Boolean} [config.jumpHigh] Whether foo should jump really high 
**/ 
function Foo(config) { 
    config = config || {}; 
    var high = config.jumpHigh; 
} 
/** 
@method jump 
@chainable 
**/ 
Foo.prototype.jump = function() { 
    // jump 
    return this; 
}; 

/** 
A series of utilities to make Foo do more stuff 

@class FooUtils 
**/ 
var FooUtils = { 
    /** 
    @method doSomeStuff 
    @static 
    **/ 
    doSomeStuff: function() { 

    } 
}; 

अंत में, @for मॉड्यूल है कि अन्य मॉड्यूल का विस्तार के लिए है। उदाहरण के लिए, आपके पास एक मॉड्यूल बार हो सकता है जो Foo के प्रोटोटाइप में विधियों को जोड़ता है:

/** 
Adds extra functionality to Foo 

@module Bar 
**/ 

/** 
Run really fast 

@method run 
@for Foo 
**/ 
Foo.prototype.run = function() {};bv