Toon posts:

API docs voor javascript

Pagina: 1
Acties:

Onderwerpen


  • X-Lars
  • Registratie: januari 2004
  • Niet online

X-Lars

Just GoT it.

Topicstarter
*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
  • Registratie: januari 2004
  • Laatst online: 21:01

MueR

Moderator Devschuur®

is niet lief

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

Anyone who gets in between me and my morning coffee should be insecure.
Breng nu uw applicatie naar de kloot. Dat is veel beter! Nu samen met klootopslag. Voor maar €9,95. Doei doei!


  • X-Lars
  • Registratie: januari 2004
  • Niet online

X-Lars

Just GoT it.

Topicstarter
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/**
 * @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.


Nintendo Switch (OLED model) Apple iPhone 13 LG G1 Google Pixel 6 Call of Duty: Vanguard Samsung Galaxy S21 5G Apple iPad Pro (2021) 11" Wi-Fi, 8GB ram Nintendo Switch Lite

Tweakers vormt samen met Hardware Info, AutoTrack, Gaspedaal.nl, Nationale Vacaturebank, Intermediair en Independer DPG Online Services B.V.
Alle rechten voorbehouden © 1998 - 2021 Hosting door True

Tweakers maakt gebruik van cookies

Bij het bezoeken van het forum plaatst Tweakers alleen functionele en analytische cookies voor optimalisatie en analyse om de website-ervaring te verbeteren. Op het forum worden geen trackingcookies geplaatst. Voor het bekijken van video's en grafieken van derden vragen we je toestemming, we gebruiken daarvoor externe tooling die mogelijk cookies kunnen plaatsen.

Meer informatie vind je in ons cookiebeleid.

Sluiten

Forum cookie-instellingen

Bekijk de onderstaande instellingen en maak je keuze. Meer informatie vind je in ons cookiebeleid.

Functionele en analytische cookies

Deze cookies helpen de website zijn functies uit te voeren en zijn verplicht. Meer details

janee

    Cookies van derden

    Deze cookies kunnen geplaatst worden door derde partijen via ingesloten content en om de gebruikerservaring van de website te verbeteren. Meer details

    janee