Ich habe ein paar Probleme damit, meine Dokumentation für eine Reihe von gruppierten Modulen zu schreiben. 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 Beispiel, das zeigt, wie der meiste Code geschrieben ist und wie ich ihn im YUIDoc-Stil dokumentiere. Die ersten beiden Teile ( Foo und BazManager ) sind ziemlich einfach. Zu mir:
Foo ist ein @class ; Baz ist ein @class ; BazManager ist ein @module (oder vielleicht ein @class , das nur @static members enthält); Qux ist auch ein @module , enthält aber nur Methoden. Meine Probleme sind:
BazManager ein @module ist, wird Foo unter BazManager ; BazManager ein @class ist, werden die Methoden innerhalb von Baz hineingezogen, wenn Sie nicht @for zu allem hinzufügen; BazManager ein @class ist, dann wird die Sichtbarkeit von Baz wirklich schwierig, Qux dokumentieren soll. Es scheint mir ein Modul zu sein, aber da es keine @class es hat, verschlingt es alles, 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 korrekt generiert wird.
Hier ist mein Beispielcode:
%Vor% In YUIDoc @class wird sowohl für klassische Klassen als auch für Objekte verwendet, die eine Menge 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 Community (mich eingeschlossen) scheinen sich von @namespace wegzubewegen. Es ist schwer, richtig zu werden. Stattdessen schreiben wir Klassennamen mit Punkten, zB: @class Plugin.NodeMenuNav .
Module sind im YUI-Sinne gemeint und können meist als "Skripte" verstanden werden, die eine oder mehrere Klassen enthalten.
Ein typisches Modul sieht dann so aus:
%Vor% Schließlich ist @for für Module gedacht, die andere Module erweitern. Zum Beispiel könnten Sie eine Modulleiste haben, die dem Prototyp von Foo Methoden hinzufügt:
Tags und Links javascript yui documentation-generation