JavaScript  »  Articoli  »  Programmazione Javascript 

I costrutti per i più esigenti

In questo secondo paragrafo analizzeremo alcuni costrutti che non sono stati analizzati in precedenza con l'esempio, ma che comunque possono essere utili in alcuni casi. 

Per i descrittori non citati in questo paragrafo non posso che rimandare alla documentazione ufficiale sul wiki del progetto.

• @author: permette di definire all'interno della nostra classe l'autore del codice sorgente. E' possibile inserire link utilizzando codice HTML. Questo costrutto non presenta un contesto fisso ma può essere applicato ad una classe, ma anche ad un metodo particolare, differenziando l'autore anche all'interno della stessa classe;
• @constant: documenta una costante all'interno del codice;
• @example: permette di inserire un esempio di utilizzo di una particolare classe o di un metodo all'interno della documentazione per spiegare meglio il comportamento dell'oggetto;
• @fileOverview: aggiunge informazioni relative al file all'interno dell'HTML generato;
• @ignore: comunica al parser di JsDoc di ignorare un particolare componente e quindi di non inserirlo nella documentazione (è differente da @private)
• @link: permette di inserire all'interno di una descrizione un link verso un'altra classe documentata dell'applicazione;
• @private: permette di definire una proprietà o un metodo come privato e quindi non direttamente richiamabile dall'esterno;
• @static: definisce un particolare membro come statico e quindi relativo alla classe in sé e non ad una particolare istanza;
• @throws: definisce se il metodo può lanciare particolari eccezioni;
• @version: permette di aggiungere il numero di versione alla documentazione.

I parametri da linea di comando

Per generare la documentazione abbiamo utilizzato un comando abbastanza semplice al quale abbiamo semplicemente impostato la cartella iniziale contenente i file .js e quale template utilizzare. È possibile però, tramite opzioni apposite, migliorare l'usabilità del comando dalla console. Anche in questo caso introdurremo i principali. Per chi volesse approfondire rimando alla pagina del wiki.

• -a: include nella documentazione tutti i metodi, anche quelli non documentati;
• -d=<PATH>: permette di impostare un percorso di destinazione differente da quello di default (che ricordo è la cartella out all'interno di JsDoc Toolkit);
• -o=<PATH>: stampa eventuali log in un file invece che nello standard output (la console dove viene eseguito il comando);
• -p: include nella documentazione anche i membri definiti come privati o quelli che iniziano con un underscore (che nella convenzione JavaScript rappresentano proprio i membri privati);
• -r=<DEPTH>: permette di eseguire uno scan ricorsivo della cartella dei sorgenti fino ad un massimo di profondità impostabile tramite <DEPTH>;
• -s: esclude i sorgenti dall'HTML generato;
• -t=<PATH>: imposta una cartella contenente il template da utilizzare (questo è l'unico parametro richiesto oltre alla cartella contenente i sorgenti);
• -v: esegue il comando con una verbosità maggiore.

Gli aspetti avanzati

Nonostante tutto quello visto finora non può che essere sufficente per uno strumento per generare documentazioni, in JsDoc Toolkit sono presenti alcune caratteristiche che gli permettono di essere considerato senza dubbi il miglior strumento di questo tipo per JavaScript.

Oltre alla presenza di componenti avanzati come il gestore di namespace e la possibilità di documentazioni inline quello che più colpisce in JsDoc Toolkit è la modularità e quindi la possibilità di estenderlo. 

È possibile aggiungere dei template personalizzati utilizzando JavaScript e un linguaggio di templating creato apposta dagli sviluppatori di nome JsPlate. Tramite JavaScript è possibile lavorare direttamente con i metadati presenti nei nostri sorgenti, analizzarli e eventualmente modificarli, mentre con JsPlate è possibile generare file HTML ma non solo in maniera rapida e indolore garantendo quindi una personalizzazione pressochè totale dell'output.

Sul sito ufficiale sono presenti due tutorial per comprendere il meccanismo e per iniziare a realizzare il proprio template, uno appunto per la componente JavaScript e uno per JsPlate. Inoltre per chi è interessato è possibile anche analizzare i sorgenti presenti nel template fornito in bundle con JsDoc.

Conclusioni

In questo articolo abbiamo imparato non solo come realizzare una documentazione in maniera rapida dai sorgenti, ma anche quali sono le motivazioni che ci devono spingere a eseguire questo compito molto spesso troppo noioso ma, ahimè, necessario soprattutto quando si lavora con altre persone. 

Il miglior modo per evitare la noia è quello di documentare passo passo il codice in modo da non trovarsi alla fine dell'implementazione con uno scoglio troppo imponente da superare. Alla prossima :)

Altri articoli

Altre guide

Altre newsletter