JavaScript  »  Articoli  »  Programmazione Javascript 

Molto spesso l'attività del programmatore va al di là della semplice scrittura di codice. Questo è uno degli aspetti che molti, incluso il sottoscritto, amano in questa professione che permette di non soffermarsi su una sola attività ma di spostarsi da compiti diversi.

Una di queste attività è proprio quella di documentare il codice.

Creare delle documentazioni, nonostante possa sembrare un'attività spesso inutile e molto laboriosa, presenta notevoli vantaggi sia quando si lavora in team sia quando si lavora da soli. Ovviamente lavorando in team una documentazione esaustiva non può che giovare sui componenti in quanto hanno una base di partenza che gli permette di capire il comportamento del codice scritto da altri. Nel caso invece si lavori ad un progetto in solitaria una buona documentazione è utile non tanto durante lo sviluppo ma nei periodi successivi, quando magari si riprende in mano il codice per eventuali bug-fix o implementazioni di nuove funzionalità: è molto frequente infatti dimenticarsi cosa si è fatto in passato.

Qualsiasi linguaggio presenta almeno un tool per la generazione di documentazioni, spesso rilasciato proprio dal team di sviluppo del linguaggio stesso. Questi strumenti non fanno nient'altro che leggere i commenti al codice inseriti nei file dei sorgenti e formattarli (spesso in pagine HTML) per renderli più leggibili, navigabili (grazie ai link HTML) e indipendenti dal codice. Ovviamente i commenti gestiti da questi strumenti di documentazione devono sottostare ad alcune regole che permettono di identificarli come “commenti da documentazione” e non come semplici commenti inseriti nel codice dallo sviluppatore.

JsDoc Toolkit: un primo sguardo

JsDoc Toolkit è un'applicazione scritta in JavaScript ed eseguita all'interno di una macchina virtuale Java che permette di generare documentazione in HTML (ma anche XML, JSON e qualsiasi altro formato di testo) partendo da sorgenti scritti in JavaScript.

è uno strumento molto avanzato e permette di configurare praticamente qualsiasi suo aspetto sia grafico (utilizzando diversi template o realizzandone uno personalizzato) sia logici (creando veri e propri plugin grazie alle comode API esposte).

JsDoc Toolkit richiede una versione della JRE abbastanza recente (la 6) e viene avviato eseguendo il file jsrun.jar (tramite il comando java -jar). Un esempio di utilizzo (a partire dalla root di JsDoc Toolkit) potrebbe essere:

java -jar jsrun.jar app\run.js -a -t=templates\jsdoc MiaClasse.js

Cosi facendo verrà generata la documentazioni per il file MiaClasse.js utilizzando il template definito all'interno della cartella templates/jsdoc (ovviamente ci sono altre impostazioni che possono essere configurate, ma le vedremo successivamente).

Attualmente il progetto è arrivato alla release 2.0.2 ed è hostato sulla piattaforma Google Code al seguente indirizzo http://code.google.com/p/jsdoc-toolkit/ mentre il sito ufficiale del progetto è http://www.jsdoctoolkit.org.

Un esempio di documentazione realizzata con JsDoc Toolkit è la documentazione del framework JavaScript Proton reperibile a questo indirizzo: http://docs.jproton.com.br (è in portoghese ma serve solo per far capire cosa andremo a generare).

Questo articolo seguirà un filone abbastanza pratico e pragmatico: vedremo in pratica come documentare un insieme di classi introducendo mano a mano nuovi argomenti.

Altri articoli

Altre guide

Altre newsletter