Documentazione di classi e moduli in YUIDocs

Question

Ho un po 'di problemi a scrivere la mia documentazione per un insieme di moduli raggruppati. Penso che sia in parte un equivoco su cosa rappresentano @class, @module e @namespace. (O forse è il risultato di Yahoo cercando di calzare un vocabolario "classico" in JS.)

Ho un campione sgrossato di seguito che mostra come la maggior parte del mio codice è scritto e il mio tentativo di documentarlo in YUIDoc -stile. Le prime due parti (Foo e BazManager) sono piuttosto semplici. Per me:

• Foo è un @class;
• Baz è un @class;
• BazManager è un @module (o forse un @class che contiene solo membri @static);
• Qux è anche un @module ma contiene solo metodi.

I miei problemi sono:

1. Se BazManager è un @module, Foo si presenta sotto BazManager;
2. Se BazManager è un @class, i metodi all'interno di Baz vengono risucchiati in esso se non si aggiunge @for a tutto;
3. Se BazManager è un @class, documentare la visibilità dello Baz diventa davvero complicato;
4. Non so davvero come dovrei documentare Qux. Mi sembra un modulo, ma dal momento che non ha uno @class, mangia tutto ciò che lo circonda, incluso lo BazManager. Quindi deve essere un @class.

Qualcuno può suggerire come dovrei farlo? Non mi interessa davvero se ottengo i termini giusto finché tutto nella documentazione viene generato correttamente.

Ecco il mio codice di esempio:

// 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 viene utilizzato per entrambe le classi classiche e per gli oggetti che contengono un sacco di metodi. Le classi che devono essere istanziate sono contrassegnate anche con @constructor. Questo è principalmente dovuto al modo in cui tali classi vengono quindi mostrate nei modelli. È molto più facile rintracciare una classe rispetto a molte funzioni solitarie.

Il team di YUI e molti membri della comunità (incluso me stesso) sembrano allontanarsi dallo @namespace. È difficile avere ragione. Invece stiamo scrivendo nomi di classi con dei punti, ad esempio: @class Plugin.NodeMenuNav.

I moduli sono intesi nel senso YUI e possono essere generalmente intesi come "script" che contengono una o più classi.

Quindi un tipico modulo sarà simile a questa:

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

    } 
}; 

Infine, @for si intende per i moduli che si estendono altri moduli. Ad esempio, potresti avere una barra modulo che aggiunge metodi al prototipo di Foo:

/** 
Adds extra functionality to Foo 

@module Bar 
**/ 

/** 
Run really fast 

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