Dokumentacja klas i modułów w YUIDocs

Question

Mam problem z napisaniem mojej dokumentacji dla zestawu zgrupowanych modułów. Sądzę, że częściowo jest to błędne przekonanie co do tego, co reprezentują. (A może wynika to z tego, że Yahoo próbuje zestawić "klasyczne" słownictwo językowe w JS).

Poniżej przedstawiam, w jaki sposób napisano większość mojego kodu i próbę jego udokumentowania w YUIDoc -styl. Pierwsze dwie części (Foo i BazManager) są dość proste. Dla mnie:

• Foo to @class;
• Baz jest @class;
• BazManager to @module (lub może @class, który zawiera tylko @static członków);
• Qux to także @module, ale zawiera tylko metody.

Moje problemy to:

1. Jeśli BazManager jest @module, Foo pokazuje się pod BazManager;
2. Jeśli BazManager jest @class, metody wewnątrz Baz zostaną wessane do niego, jeśli nie dodasz do wszystkiego @for;
3. Jeśli BazManager jest @class, to dokumentacja widoczności Baz staje się naprawdę trudna;
4. Naprawdę nie wiem, jak mam udokumentować Qux. Wydaje mi się, że jest to moduł, ale ponieważ nie ma on żadnych znaczników, to pożera wszystko wokół niego, w tym BazManager. Więc musi to być @class.

Czy ktoś może zasugerować, w jaki sposób powinienem to zrobić? Naprawdę nie obchodzi mnie, czy otrzymam odpowiednie warunki, o ile wszystko w dokumentacji zostanie wygenerowane poprawnie.

Oto mój przykładowy kod:

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

W YUIDoc @class służy do obu klas klasycznych i obiektów, które zawierają kilka sposobów. Klasy, które mają być tworzone, są również oznaczone jako @constructor. Wynika to głównie ze sposobu, w jaki te klasy są następnie wyświetlane w szablonach. O wiele łatwiej jest wyśledzić klasę niż wiele samotnych funkcji.

Zespół YUI i wielu członków społeczności (w tym mnie) wydaje się oddalać od @namespace. Trudno to naprawić. Zamiast tego piszemy nazwy klas z kropkami, np .: @class Plugin.NodeMenuNav.

Moduły mają znaczenie YUI i można je w większości rozumieć jako "skrypty" zawierające jedną lub więcej klas.

więc typowy moduł będzie wyglądać następująco:

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

    } 
}; 

Wreszcie @for jest przeznaczona dla modułów, które rozszerzają inne moduły. Na przykład można mieć moduł Bar, która dodaje metody prototypu Foo:

/** 
Adds extra functionality to Foo 

@module Bar 
**/ 

/** 
Run really fast 

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