API docs voor javascript

[Clay]

Ik ben een beetje aan het rondkijken wat er allemaal voor API doc generators zijn die voor javascript werken, en vroeg me af of er al meer mensen dit gedaan hebben en een goeie suggestie hebben (ook als het "doe het niet!" is).

Eentje is bv de jsDoc toolkit, een comment based javadoc achtig ding die wel werkt, maar omdat die zelf je functions checkt gaat die gruwelijk op zn gat met anymous closure constructies voor bv een jQuery component ala:

JavaScript:

(function($){
   /** en hier een class bouwen */
})(jQuery);

Natural docs ziet er wel aardig uit, maar ik ben een beetje huiverig om van die javadoc syntax af te stappen eigenlijk. Het kan het wel, maar niet alles oid, en dan biedt het eigenlijk ook geen meerwaarde meer.

Een goeie kanshebber vind ik tot nu toe YUIDoc; wederom die javadoc syntax, maar je kan wat meer dingen handmatig opgeven zodat je je vage closures kan blijven gebruiken. Modules en Classes kan je lekker van elkaar scheiden, en het ziet er erg bruikbaar en vriendelijk uit. Je moet die python zwik ff aan de gang krijgen, maar daarna kan je het helemaal stylen naar je eigen inzicht.

Op wiki staat een hele comparison met nog veel meer generators, misschien nog wel veel briljantere dan de bovenstaande, vandaar dat ik er hier ff naar vraag.

[Copyman]

Afgelopen week was ik bezig met ScriptDoc, een onderdeel van Aptana. Deze werkt vrij goed, maar als ik de Javascript Module Pattern toepas wordt het een zooitje. Alles komt dan door elkaar te staan op de één of andere manier.

Bedankt voor de andere links, ik wilde deze week ook op zoek gaan naar wat alternatieven.

[Clay]

Da's hetzelfde waar jsDoc ook van op zn gat gaat ja, daar heb ik dus echt niks aan

[_Thanatos_]

Niet dat het helpt, maar ik geloof niet zo in die generators. Ze zijn namelijk heel herkenbaar: ze generen documentatie waar een gebruiker (coder) vrij weinig aan heeft. De documentatie bij een class (object-prototype eigenlijk, in JS) is vaak zo summier dat het alleen beschrijven wat het doet. Maar wat een programmeur wil weten, is wat je ermee kan, waar je het aan kunt doorgeven, hoe je eraan kan komen, etc. Zelfde geldt voor functie-argumenten: als die van een bepaald obscuur type zijn, zie je vaak niet uitgelegd hoe je zo'n ding dan instantiëert of ergens uit oplepelt.

Ik zou zelf dus m'n objecten niet te ingewikkeld maken, en zeker niet ingewikkelder dan wat de applicatie(s) of project(en) vereisen, en de documentatie richten op gebruikers van je code, niet op jezelf. En dat kan een mens alleen