JavaScript Dokumentation mit YUIDoc

German (Deutsch) translation by Kaspar Thomann (you can also view the original English article)

Quellcode zu dokumentieren ist vergleichbar mit Testen! Wir alle wissen dass es getan werden soll, doch wie es angehen? Und, sind wir mal ehrlich, viele tun es einfach nicht. Diejenigen welche wirklich testen und dokumentieren sind die wirklich Professionellen. Diese Anleitung wird Sie schnell und einfach in die Lage versetzen YUIDoc anzuwenden.

Was ist YUIDoc?

YUIDoc erzeugt eine API Dokumentation welche aus den Kommentaren im Code aufbereitet wird.

YUIDoc ist eine NodeJS App welche eine API Dokumentation (auf HTML Basis) erzeugt. Die Angaben stammen ausschliesslich aus dem JavaScript Quellcode. Überhaupt ist YUIDoc nicht nur für JavaScript Codes; jede andere Programmiersprache kann mit Hilfe von YUIDoc kommentiert werden, solange diese die Begrenzugszeichen /* */ zulässt. Wie vielleicht vermutet wird ist YUIDoc ein Werkzeug von Yahoo! welches im Rahmen deren YUI Library publiziert wird.

Um YUIDoc zu installieren wird NodesJS und der Node Package Manager (npm) vorausgesetzt. Sind die Voraussetzungen erfüllt, lässt sich YUIDoc (in der Rolle admin bzw. superuser) installieren über npm -g install yuidocjs Somit kann YUIDoc benutzt werden. Nutzen Sie schon mal (als normaler User) den Befehl yuidoc -v um sich die installierte Version anzeigen zu lassen. Weiter unten folgt mehr dazu.

Es geht um die Markierungen!

Sie wissen nun dass YUIDoc die Dokumenation über mehrere Zeilen lange Kommentare in der Quellcode Datei erzeugt. Klar werden auch Kommentare im Quellcode stehen, die nicht in die offizielle Dokumentation hinein gehören. Um YUIDoc zu den wichtigen Kommentaren zu leiten muss ein entsprechender Teil mit dem Doppelstern beginnen: /** Hier ein Beispiel:


/**
YUIDoc will process this
*/

/* 
But not this
*/

Natürlich zählt eben nur was sich innerhalb der Kommentar Blocks befindet. Davon muss sich in jedem Block eines oder gleich mehrere Haupt-Kennzeichen befinden. Zusätzlich können dann auch noch Unter-Kennzeichen vorhanden sein. Wirklich, YUIDoc ist ganz einfach: Kommentare mit den entsprechenden Kennzeichnungen im Quellcode erfassen, und voilà: Dokumentation! Hier sind schon die ersten Haupt-Kennzeichen zum Beginn. Wir gehen wie folgt vor: Anhand einfacher Beispiel wird der Gebrauch der Haupt-Kennzeichen aufgezeigt. Dann schreiben und dokumentieren wir etwas Quellcode um noch deutlicher zu sein wie diese Kennzeichnungen zusammenwirken.

Haupt-Kennzeichen

Zur Wiederholung: denken Sie daran dass jeder einzelne Kommentar-Block nur ein einziges Haupt-Kennzeichen enthalten darf. Auf diese Weise enthält jeder Block eine Erklärung zum Code, was genau geschieht.

`@module`

Mit dem @module Tag werden die darin enthaltenen Klassen beschrieben. (Na klar, aber JavaScript kennt gar keine Klassen: YUIDoc bezieht sich damit auf Kontruktor Funktionen in diesem Modul.) Sollte BackboneJS bspw. mit YUIDoc beschrieben werden, so würde das Backbone Objekt als Modul erfasst werden, da es Model, Collection, View, und noch weitere Klassen enthält. Gleich nach dem @modul Kennzeichen folgt der eigentliche Modul-Name.


/**
@module Backbone
 */
 var Backbone = Backbone || {};

`@class`

Mit dem @class Tag wird eine einzelne Klasse beschrieben. In der YUI Library wird damit eine Konstruktor Funktion bezeichnet. Doch sollten andere Meinungen bestehen wofür dieser Tag verwendet werden sollte, ist dies auch zulässig. Jeder Kommentar zum @class Tag könnte zusätzlich mit @static oder @constructor Tag ergänzt werden.


/**
@class Model
 */
 function Model () {}

Sollte die Klasse Teil eines Modules sein braucht man im @class Kommentar nichts weiteres dafür vorzumerken. Es muss lediglich ein @module Kommentar Block zu Beginn dieser Datei vorhanden sein.

`@method`

Bestimmt hat jede Klasse ein paar Methoden. So wird jede Methode mit einem @method Tag beschrieben. Der Name der Methode folgt unmittelbar darauf und mit @return und @params wird die Methode dann weiter beschrieben.


/**
@method render
*/
View.prototype.render = function (data) {}

`@property`

Mit dem @property Tag werden die Eigenschaften einer Klasse aufgeführt. Sie werden bestimmt auch @type und @default Tag verwenden


/**
@property templateString
*/
this.templateString = "div";

`@event`

Arbeitet eine Klasse mit Events, so wird der @event Tag zur Beschreibung der Ereignisse benutzt. Lesen Sie was die YUIDoc Dokumentation dazu schreibt:

Ein @event Block ist vergleichbar mit dem @method Block, mit dem Unterschied dass @return völlig irrelevant ist, und @param zur Beschreibung der Eigenschaft im Zusammenhang mit dem Callback zum Event Objekt verwendet wird.

Sekundäre Tags

Kommentarblöcke können mehr als einen Sekundär Bezeichner enthalten; vielmehr sind davon gleich mehrere vorhanden und zudem erscheint derselbe Type gleich merhfach. Schauen wir uns doch die wohl am häufigsten benutzten Secondary Tags an.

`@submodule - Unter-Modul`

Sollten die Module weiter unterteilt werden (vielleicht ein Submodul pro Datei, oder auch nicht), so wird das @submodule Tag zur Einteilung benutzt.


/**
@module Util
@submodule array
*/
Util.array = {};

`@extends - erweitert`

Das @extends Tag wird für Beziehungen zwischen Superclass / Subclass eingesetzt. Man kann damit den Parent der aktuell beschriebenen Class bestimmen.


/**
@class AppView
@extends Backbone.View
*/
var AppView = Backbone.View.extend({});

`@constructor`

Eine Class wird in der Regel durch eine Konstruktor-Funktion instanziiert. Mit der standard Prototype Verwendung in JavaScript ist die Class Deklaration auch gleich der Konstuktor. Somit wird meist folgendes zu sehen sein:


/**
@class Recipe
@constructor
*/
function Recipe () {}

Man wird sich möglicherweise an meine Aussage erinnern, dass jede @class entweder ein @constructor oder ein @static Tag (Sekundärer Bezeichner) haben solle.

`@static - statisch`

Apropos @static, hier kommts. Von einer static Class kann keine Instanz gebildet werden. Ein gutes Beispiel dafür ist das eingebaute Math Objekt: davon wird nie eine Instanz erstellt ( new Math() ). Die Methoden werden immer dirket von der Class selbst benutzt.


/**
@class MathHelpers
@static
*/
var MathHelpers = {};

Methoden können auch static sein: in einer instanziierten Class sind Methoden auf der Class-Ebene statisch (sie werden über die Class aufgerufen und nicht über die Instanz).


/**
@class Person
@constructor
*/
function Person () {}

/**
@method all
@static
*/
Person.all = function () {};

In diesem Beispiel hier kann eine Instanz von Person kreiert werden, doch die all Methode ist static.

`@final`

Dieses Tag wird für Eigenschaften bzw. Attribute benutzt, und markiert diese als Konstante: also nicht verändern. Da JavaScript z.Zt. keine wirklichen Konstanten kennt, soll doch im Code oder in der Beschreibung dazu auf konstante Werte hiigewiesen werden können.


/**
@property DATE_FORMAT
@final
*/
var DATE_FORMAT = "%B %d, %Y";

`@param`

Hier kommt was sehr wichtiges: mit dem @param Tag sind Parameter für @method (eingeschliesslich @constructor ) und auch solche für @event beschrieben. Jeder @param wird mit drei Teilen genauer umschrieben: sein Name, dessen Type (optional) sowie die Beschreibung. Diese können entweder in der Reihefolge Name Type Beschreibung oder Type Name Beschreibung vorliegen; in jedem Fall aber muss Type in geschweiten Klammer stehen.


/**
@method greet
@param person {string} The name of the person to greet
*/
function greet (person) {}

Auch gibt es diverse Arten mit dem Paramter Name weitere Angaben dazu zu erfassen. Optionale Parameter-Namen stehen in eckigen Klammern. Die zusätzliche Angabe wie =einWert verdeutlicht eine allfällige Voreinstellung (offensichtlich aber besitzen nur optionale Parameter eine solche Angabe). Platzhalter für mehr als ein Argument bekommen ein * angefügt, um dies anzuzeigen. (Offenkundig ist name* ein Platzhalter für 1 oder mehrere Argumente, während [name]* ein solcher für 0 oder mehrere Argumente beschriebt).


/**
@class Template
@constructor
@param template {String} The template string
@param [data={}] {Object} The object whose properties will be rendered in the template
*/
function Template (template, data) {}

`@return`

Meistens wird eine Methode einen Rückgabewert senden. Mit diesem Tag wird der Rückgabewert beschrieben. Der Type des Rückgabewertes und ein Beschreibung dazu sollten selbstverständlich mit dabei sein.


/**
@method toHTML
@param [template=Recipe.defaultTemplate] {Template} A template object
@return {String} The recipe contents formatted in HTML with the default or passed-in template.
*/
Recipe.prototype.toHTML = function (template) {
    return "whatever";
};

`@type`

Oben wurde doch der @property Tag beschrieben, ja? Sicher sollen Angaben zum Type von Eigenschaften (properties) vorhanden sein! Nun, der @type Tag ist genau dazu geeignet. Spezifizieren Sie den Type nach diesem Tag. Mehrfache Typen werden durch vertikale Striche getrennt:


/**
@property URL
@type String
*/
URL: "http://net.tutsplus.com",

/**
@property person
@type String|Person|Object
*/
this.person = new Person();

`@private` / `@protected`

Traditionelle Programmiersprachen besitzen private Eigenschaften und Methoden: ausserhalb der Instanz nicht zugängliche Komponenten. Genau gleich wie schon bei Konstanten gesehen, verhält sich JavaScript mit dem @private Tag. Private Komponenten existieren nur in der Handhabung der Programmierung, die Sprache selbst kennt sie (noch) nicht. Für YUIDoc ist jedoch bemerkenswert dass private Einheiten in der generierten Dokumentation nicht erscheinen. Damit sind solche Angaben echt privater Natur. Sie bleiben Ihnen vorbehalten und werden nicht publiziert.


/**
@method _toString
@private
*/
var _toString = Object.prototype.toString.call;

Protected Eigenschaften und Methoden befinden sich halbwegs zwischen öffentlich undprivat: sie nur innerhalb der Instanz und SubClasses davon zugänglich. Sollte dies im JavaScript vorkommen, hier ist der Tag dazu: @protected .

`@requires`

Sollte ein Module von anderen abhängig sein, wird dies mit @requires markiert.


/**
@module MyFramework.localstorage
@requires MyFramework
*/

In @requires kann gleich eine Liste von anbhängigen Modulen erscheinen. Die Namen werden durch Komma getrennt.

`@default`

Oftmals ist ein @default Wert für ein @property wünschenswert. Für @default sollte immer eine @type Angaben vorhanden sein.


/**
@property element
@type String
@default "div"
*/
element: "div",

`@uses`

Wie schon gesagt, JavaScript hat nicht wirkliche Classen, aber es ist felxibel genug um die Illusion von Classen und sogar von Sub-Classen zu unterstützen. Und was noch cooler ist, ist dass Mengen oder Module möglich sind, worin eine Class Eigenschaften oder Methoden von anderen Classen "borgt". Aber es ist dennoch keine Vererbung, da Teile von mehr als einer Class vermengt werden dürfen. (Natürlich kennen YUI, Dojo und andere Libraries dies Möglichkeit auch). Sollte dies nötig sein, so wird @uses dazu benutzt: damit lassen sich Mengen aus verschiedenen Classen aufzeigen.


/**
@class ModalWindow
@uses Window
@uses DragDroppable
*/
var ModalWindow = new Class({
    mixes: [Window, DragDroppable],
    ...
});

Beachte: Ich habe diesen Mengen Syntax gemacht, doch bin ich sicher dies schon mal irgendwo anderes gesehen zu haben.

`@example`

Es soll ein Beispiel her wie ein bestimmtes Stück benutzt werden soll? Dafür ist der @example Tag gedacht. Unten nach folgt das Beispiel, gleich um eine Stufe weiter eingerückt. Und es können soviele Beispiele wie gewünscht platziert werden.


/**
@method greet
@example
    person.greet("Jane");
*/
Person.prototype.greet = function (name) {};

`@chainable`

Vielleicht sind Verkettungen von Methoden aus jQuery bekannt. Gemeint ist, dort wo Methoden Aufruf auf Aufruf folgt, weil jede Methode ein Object zurück liefert. Solche Methoden werden daher durch @chainable markiert.


/**
@method addClass
@chainable
*/
jQuery.prototype.addClass = function (class) {
    // stuff;
    return this;
}

`@deprecated` / `@since` / `@beta`

Diese drei Tags sind Aussagen zum Support von Codes (und gemeint ist jegliche Art von Code: Module, Classen, Methoden oder andere Teile). Mit @deprecated werden Teile markiert welche nicht mehr weiter benutzt werden sollten, da mittlerweile besseren Ersatz dafür exsitiert. (So markierte Teile könnten in einer zukünftigen Version wegfallen). Zusätzlich kann eine Erklärung den neuen Weg aufzeigen.


/**
@method toJSON
@deprecated Pass the object to `JSON.parse` instead
*/
Something.toJSON = function () {};

Der @since Tag erklärt, ab welcher Version der entspr. Code hinzu kam. Und mit @beta wird eben genau Beta-Code beschrieben: YUI meint, dass für mit @beta markierte Teile "in naher Zukunft eine Unverträglichkeit mit älteres Codes einhergehen könne".


/**
@class Tooltip
@since 1.2.3
@constructor
*/
function Tooltip () {}

`@extension` / `@extensionfor` / `extension_for`

Der @extension Tag (und dessen Aliases) ist ziemlich genau das Gegenteil von @uses. Dies um anzuzeigen welche Class einer Extension-Class beigemischt werden kann. Es sollte klar sein, dass eine Beimischung möglich wäre, aber nicht in jedem Falle sein muss.


/**
@class Draggable
@extensionfor ModalWindow
*/

Kommentare und Markdown (vereinfachte Auszeichnungen)

Hiernach wird ein aktuelles Beispiel gezeigt, wobei ich zwei drei Dinge zur Dokumentation von Kommentarblöcken zeigen möchte.

Erstens: Meistens möchte man etwas mehr an Informationen über den Code liefern, als wofür der aktuelle Tag wirklich gut ist. Vielleicht um den Zweck von Methoden zu beschreiben, oder wie eine Class ins Gesamtbild hinein passt. Solche Kommentare werden ganz zu Beginn im Block notiert, oberhalb jeglicher Tags. YUIDoc wird dies erkennen und diese Teile in die Dokumentation einschliessen.


/**
The `Router` class is used for . . .
@class Router
@static
*/
var Router = {};

Zweitens: erfreulicherweise können Kommentare und Beschreibungen jeweils nach Tags in einfacher Auszeichung (Markdown) formatiert werden, und YUIDoc wird auch die formatierten Teile korrekt in HTML umwandeln. Auch eingerückter Beispielcode kann in Kommentaren sein, dessen Syntax wird hervorgehoben!

Ein Beispiel

Nun da alle Tags vorgestellt wurden wird etwas Code geschrieben um diesen anschliessend zu dokumentieren. Wir bauen ein Store Module mit den beiden Classen Item und Cart. Jede Item Instanz findet sich in der Artikelliste des Warenhauses mit Name, Preis und einer Mengenangabe. Der Cart kann mit Artikeln gefüllt werden, wobei der Gesamtpreis aller Artikel im Warenkorb berechnet wird (inkl. MWSt.) Diese Aufgabe ist realtiv einfach gehalten, doch zeigt sie genügend Funktionen um einige der vorgestellten Tags anzuwenden. Der folgende Code ist in der Datei store.js gespeichert.

Nun wird das Modul erzeugt:


/**
* This module contains classes for running a store.
* @module Store
*/

var Store = Store || {};

Nun wird eine "Konstante" erzeugt: die MWSt. ( TAX_RATE )


/**
* `TAX_RATE` is stored as a percentage. Value is 13.
    * @property TAX_RATE
    * @static
    * @final
    * @type Number
*/

Store.TAX_RATE = 13;

Da dies eine Konstante ist wird durch @final deutlich gemacht. Dem @property Tag wird der Name zugefügt und dass es sich um eine Zahl handelt beschreibt der @type Tag. Zu beachten ist der @static Tag: da YUIDoc sonst TAX_RATE als Eigenschaft der Item Class generiert; es scheint dass YUIDoc sonst keine Eigenschaften auf Modulebene haben möchte. Es könnte vermutlich eine statische Class erzeugt werden um diese Konstante aufzunehmen (und allenfalls weitere, falls der Code ausgebaut würde), doch soll es jetzt einmal so stehen bleiben als Mahnung, um zu zeigen dass YUIDoc nur ganz ausgereitzt werden könnte wenn man nur entsprechend programmiert. Ob Sie dies wirklich möchten bleibt Ihnen überlassen!

Nun, für die Item Class:


/**
 * @class Item
 * @constructor
 * @param name {String} Item name
 * @param price {Number} Item price
 * @param quantity {Number} Item quantity (the number available to buy)
 */

Store.Item = function (name, price, quantity) {
    /**
     * @property name
     * @type String
     */
    this.name = name;
    /**
     * @property price
     * @type String
     */
    this.price = price * 100;
    /**
     * @property quantity
     * @type Number
     */
    this.quantity = quantity;
    /**
     * @property id
     * @type Number
     */
    this.id = Store.Item._id++;
    Store.Item.list[this.id] = this;
};

Leicht zu sehen sind die drei Parameter des Konstuktors. Zum Konstruktor gehören drei Eigenschaften welche auch beschrieben werden. Da jedes Item zudem mit einer ID gekennzeichnet wird, braucht es dazu eine statische Eigenschaft (auf Class Ebene) um die ID zu erhöhen, sowie eine weitere statische Eigenschaft welche das Item über die ID kennzeichnet.


/**
 * `_id` is incremented when a new item is created, so every item has a unique ID
 * @property id
 * @type Number
 * @static
 * @private
 */
Store.Item._id = 1;

/**
 * @property list
 * @static
 * @type Object
 */
Store.Item.list = {};

Und wie steht es mit der Cart Class?


/**
 * @class Cart
 * @constructor
 * @param name {String} Customer name
 */

Store.Cart = function (name) {
    /**
     * @property name
     * @type String
     */
    this.name = name;
    /**
     * @property items
     * @type Object
     * @default {}
     */
    this.items = {};
};

Hier ist nicht wirklich Neues zu finden: wir deklarieren das der Default- od.Initial-Wert der Item Eigenschaft ein leeres Objekt ist.

Nun, hier die Methoden. In addItem ist ein Parameter optional, weshalb dies auch so beschrieben wird, und es wird eine 1 gespeichert, falls nichts angegeben wird. Zudem ist die Methode verkettet @chainable nutzbar.


/**
 * Adds 1 or more of a given item to the cart, if the chosen quantity 
 * is available. If not, none are added.
 *
 * @method addItem
 * @param item {Object} An `Item` Object
 * @param [quantity=1] {Number} The number of items to add to the cart
 * @chainable
 */

Store.Cart.prototype.addItem = function (item, quantity) {
    quantity = quantity || 1;
    if (item.quantity &gt;= quantity) {
        this.items[item.id] = this.items[item.id] || 0;
        this.items[item.id] += quantity;
        item.quantity -= quantity;
    }
    return this;
};

Schliesslich ist die Rückgabe der Gesamtpreis inkl MWSt. Beachten Sie dass die Preisberechung in cents erfolgt um sie nachher in Dollar, auf zwei Nachkomastellen gerundet, auszugeben.


/**
 * @method total
 * @return {Number} tax-included total value of cart contents
 */

Store.Cart.prototype.total = function () {
    var subtotal, id;
    subtotal = 0;
    for (id in this.items) {
        if(this.items.hasOwnProperty(id)) {
            subtotal += Store.Item.list[id].price * this.items[id];
        }
    }
    return parseFloat(((subtotal * (1 + Store.TAX_RATE / 100)) / 100).toFixed(2));
};

Hier folgt nun ein einfacher Test um den Code überprüfen zu können.


var apple, pear, book, desk, assertEquals;

assertEquals = function (one, two, msg) {
    console.log(((one === two) ? "PASS : " : "FAIL : ") + msg);
};

apple = new Store.Item('Granny Smith Apple', 1.00, 5);
pear  = new Store.Item('Barlett Pear', 2.00, 3);
book  = new Store.Item('On Writing Well', 15.99, 2);
desk  = new Store.Item('IKEA Gallant', 123.45, 1);
cart  = new Store.Cart('Andrew');

cart.addItem(apple, 1).addItem(book, 3).addItem(desk, 1);

assertEquals(apple.quantity, 4, "adding 1 apple removes 1 from the item quantity");
assertEquals(book.quantity, 2, "trying to add more books than there are means none are added");
assertEquals(cart.total(), 140.63, "total price for 1 apple and 1 desk is 140.63");

Generierung der Dokumentation

Nun, da der Code programmiert und mit Kommentar-Blocks versehen wurde, ist es Zeit die Dokumentation zu generieren.

Wenn YUIDoc global, mit npm installiert wurde, so folgt der Aufruf mittels yuidoc {Pfad zur js Datei} In meinem Fall ist dies

1
2	yuidoc .

Nun ist ein out Verzeichnis in diesem Ordner entstanden; um die generierte Dokumentation zu lesen wird out/index.html geöffnet. Hier nun den Teil der Cart Class Dokumenation:

Ausgabe konfigurieren

YUIDoc bietet verschiedene Optionen in der Konfiguration um die Ausgabe zu steuern. Klar, alles kann über die Aufrufzeile mit Flags eingestellt werden, doch eine JSON Konfig-Datei bietet Vorteile. Dafür wird im Projekt Verzeichnis die yuidoc.json Datei erstellt. Zuerst werden generellen Projekt Informationen gesetzt; wobei diese die Ausgabe nicht wirklich gross beeinflussen. Doch ist es gut auch diese zu dokumentieren:


{
    "name": "Documenting JavaScript with YUIDoc",
    "description": "A tutorial about YUIDoc, for Nettuts+",
    "version": "1.0.0",
    "url": "http://net.tutsplus.com"
}

Dann folgt eine Anzahl von einstellbaren Optionen. Hier eine Auswahl der wohl interssanteren Optionen;

linkNatives : auf "true" eingestellt um native Typen wie String oder Number mit der MDN Doc zu koppeln.
outdir: hier lässt sich der Name des out Verzeichnisses bestimmen.
paths: steuert die Pfade wo YUIDoc nach JavaScript Dateien suchen darf.
exclude: Dateiliste, durch Komma getrennt, welche YUIDoc ingnorieren soll.

So wie die paths Option gesetzt ist, wird YUIDoc ganz einfach über yuidoc -c yuidoc.json gestartet. Auch wenn paths nicht gesetzt wurde und lediglich yuidoc . aufgerufen wird, so verwendet YUIDoc die Werte aus der Konfig Datei.

Hier folgt meine ganze Konfig Datei für dieses Projekt:


{
    "name": "Documenting JavaScript with YUIDoc",
    "description": "A tutorial about YUIDoc, for Nettuts+",
    "version": "1.0.0",
    "url": "http://net.tutsplus.com",
    "options": {
        "linkNatives": "true",
        "outdir": "./docs",
        "paths": "."
    }
}

Auswertung

Mit den in YUIDoc angebotenen Tags wird evident, dass dieses Werkzeug für JavaScript nicht nur für traditionellen OOP, sondern auch für YUI Widget u.a. sehr hilfreich ist. (Tatsächlich habe ich die YUI-spezifischen Tags weggelassen). Aus diesem Grund kann es sein dass mehrere Tags für Ihren Gebrauch nichts dienen werden. Das ist dann der Moment zu überlegen, ob die Codierung angepasst werden sollte, um diesen besser mit YUIDoc dokumentieren zu können. (orig. "match the way YUIDoc 'thinks'"). Auch wenn der Code deswegen nicht verändert wird, werden die YUIDoc Tags mehrheitlich verwendet werden können.

Die wohl wichtigere Frage für mich ist, ob die Dokumentation gleich mit und im Code vorliegen soll und mit diesem überein stimmt.

Obiges Beispiel weist 120 Zeilen mit Kommentaren auf und 40 Zeilen ohne Kommentare. Offensichtilich ist dieser Code super einfach. Bestimmt würde jedes praktische Beispiel ausgewogener wirken; doch solch vermischte Codes zu lesen ist eben auch eine Herausforderung. Persönlich denke ich, für die nächsten paar Wochen YUIDoc eine gewisse Weile nutzen zu wollen während ich codiere. Ich bin gespannt zu sehen wie dies die Art und Weise der Codierung und die Abläufe beeinflussen wird.

Die Routine macht doch alles: liebe es oder hasse es! Senden Sie mir Ihre Kommentare!

JavaScript Dokumentation mit YUIDoc

Was ist YUIDoc?

Es geht um die Markierungen!

Haupt-Kennzeichen

@module

@class

@method

@property

@event

Sekundäre Tags

@submodule - Unter-Modul

@extends - erweitert

@constructor

@static - statisch

@final

@param

@return

@type

@private / @protected

@requires

@default

@uses

@example

@chainable

@deprecated / @since / @beta

@extension / @extensionfor / extension_for