API docs voor javascript

[X-Lars]

*kick*

We zijn ondertussen 1,5 jaar verder dan de TS. Ik ben benieuwd wat jullie momenteel gebruiken om Javascript te documenteren. Ik wilde nu eens gaan beginnen met wat documentatie in een eigen project, vandaar deze brute kick.

YUI Doc zou op dit moment mijn keuze zijn. Ook al is het nogal YUI-oriented, het is ook wel weer vrij generiek en komt aardig overeen met hoe ik zelf e.e.a. opzet (modules, classes, methods etc.).

Ook YUI Doc, omdat jsdoc-toolkit (versie 2) niet meer in ontwikkeling is. Niet dat het daarmee direct af te raden is om te gebruiken (het wordt nog steeds op grote schaal gebruikt denk ik). Echter ik zie ook dat jsdoc3 er aan zit te komen... (for those interested: interview, blog op github, twitter).

Als jij nu een nieuw project zou gaan documenteren, hoe zou je het dat dan organiseren? Er even van uitgaande dat het geen minimaal hobby-projectje is.

[MueR]

Ik heb deze reactie maar even afgesplitst naar een nieuw topic.Het origineel ligt prima in de sloot, daar is het oud genoeg voor.

[X-Lars]

Is het echt zo slecht gesteld met documentatie in /13?

Uiteindelijk ben ik, na uitgebreid testen met jsdoc-toolkit, bij YUI Doc uitgekomen (simpel te installeren op Mac). Dit omdat het gewoon werkt zoals ik het graag wil. En ik heb niet zulke bijzondere eisen, maar onderstaande code documenteren is niet of nauwelijks te doen in jsdoc. Maar in YUI Doc is het geen probleem. Moet er wel bij zeggen dat laatstgenoemde ook eigenlijk simpelweg alleen in de docs opneemt wat jij expliciet documenteert in de code. jsdoc probeert erg veel uit de code af te leiden (de --nocode optie is er, maar levert overhead op) en kan niet met alle constructies overweg (zoals deze variant van de module pattern).

JavaScript:

/**
 * @module myModule
 */

(function(myApp) {
    
    /**
     * @class myApp.myClass
     */
    
    myApp.myClass = function() {
        
        var oThis = {};
        
        var reTrim = /^\s+|\s+$/g;
        
        /**
         * Trims a string, removing whitespace on left and right side
         *
         * @method trim
         * @param {String} sString The string to trim
         * @return {String} The trimmed string
         */
        
        oThis.trim = (function() {
            // 
        })();

        return oThis;
    }();

})(myApp);

Heb nu ook wat snippets in Textmate toegevoegd voor deze doc comments. Voor mij weinig redenen meer om code niet goed te documenteren. Bovenstaand is overigens slechts een voorbeeld, ik houd niet van overmatig veel (onnodige) documentatie, de code is idealiter self-explaining. Het is in ieder geval altijd handig om niet de code nodig te hebben om een overzicht te hebben van de API.