Dokumentation von Klassen und Modulen in YUIDocs

Question

Ich habe ein paar Probleme mit dem Schreiben meiner Dokumentation für eine Gruppe von gruppierten Modulen. Ich denke, es ist teilweise ein Missverständnis darüber, was @class, @module und @namespace darstellen. (Oder vielleicht ist es ein Ergebnis von Yahoo, der versucht, ein 'klassisches' Vokabular in JS zu schüren.)

Ich habe unten ein grobes Beispiel, das zeigt, wie der meiste Code geschrieben ist und mein Versuch, ihn in YUIDoc zu dokumentieren -Stil. Die ersten beiden Teile (Foo und BazManager) sind ziemlich einfach. Zu mir:

• Foo ist ein @class;
• Baz ist ein @class;
• BazManager ist eine @module (oder vielleicht eine @class, die nur @static Mitglieder enthält);
• Qux ist auch eine @module aber enthält nur Methoden.

Meine Probleme sind:

1. Wenn BazManager ein @module ist, Foo zeigt sich unter BazManager;
2. Wenn BazManager ein @class ist, werden die Methoden innerhalb Baz hineingesaugt, wenn Sie nicht @for zu allem hinzufügen;
3. Wenn BazManager ein @class ist, dann wird die Sichtbarkeit von Baz wirklich schwierig;
4. Ich weiß wirklich nicht, wie ich Qux dokumentieren soll. Es scheint mir ein Modul zu sein, aber da es keine @class es hat, verschlingt es alles um ihn herum, einschließlich BazManager. Also muss es ein @class sein.

Kann jemand vorschlagen, wie ich das tun sollte? Es ist mir egal, ob die Bedingungen richtig sind, solange alles in der Dokumentation richtig generiert wird.

Hier ist mein Beispielcode:

// 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

In YUIDoc @class für beide klassischen Klassen verwendet wird und für Objekte, die eine Reihe von Methoden enthalten. Klassen, die instanziiert werden sollen, sind ebenfalls mit @constructor gekennzeichnet. Das liegt hauptsächlich an der Art und Weise, wie diese Klassen dann in den Vorlagen angezeigt werden. Es ist viel einfacher, eine Klasse aufzuspüren als viele einzelne Funktionen.

Das YUI-Team und viele in der Gemeinde (mich eingeschlossen) scheinen sich von @namespace zu entfernen. Es ist schwer, richtig zu werden. Stattdessen schreiben wir Klassennamen mit Punkten, zB: @class Plugin.NodeMenuNav.

Module sind im Sinne von YUI gemeint und können meist als "Skripte" verstanden werden, die eine oder mehrere Klassen enthalten.

So ein typisches Modul wird wie folgt aussehen:

/** 
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() { 

    } 
}; 

Schließlich wird @for für Module gemeint, die anderen Module erweitern. Zum Beispiel könnten Sie eine Modulleiste haben, die dem Prototyp von Foo Methoden hinzufügt:

/** 
Adds extra functionality to Foo 

@module Bar 
**/ 

/** 
Run really fast 

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