Visual Studio: documentare il proprio codice sorgente 26 Maggio 2010
Inviato da LukePet in : Chicche, Documenti, Guide, Informatica, Prodotti, Software, Sviluppo, Tecnologia, Tutorial, Windows , trackbackEcco un altro post che attraversa il versante più “tecnico” dei contenuti di questo blog. Dopo averne già parlato poco tempo fa, torno ad affrontare l’argomento Visual Studio…e per la precisione: “Visual Studio & documentazione del codice”.
Qualche settimana fa mi sono deciso a produrre un po’ di documentazione tecnica in riferimento ad un progetto che sto portando avanti dove lavoro, così mi sono messo a ricercare una soluzione che mi soddisfacesse. Dopo qualche test sono riuscito a trovare una configurazione ideale per tenere allineata la documentazione del mio codice sorgente. Ora, visto che in rete (aldilà di qualche discussione) non ho trovato grossi tutorials a riguardo, riporto in questo post tutte le linee guida che ho seguito. Magari può tornare utile a qualcuno.
Punto 1° – Commentare sempre il codice!
Avere del codice ben commentato è fondamentale, se poi i commenti sono ben strutturati sarà possibile integrarli nella propria documentazione senza problemi. Insomma, abituatevi a fare una cosa come questa:
/// <summary>
/// This is MyFunction
/// </summary>
/// <param name="param1">First parameter</param>
/// <param name="param2">Second parameter</param>
/// <returns>My return value</returns>
public int MyFunction(string param1, double param2)
{
}
per avere un’idea più chiara dei tags che potete sfruttare nella scrittura dei vostri commenti buttate un occhio qua: Recommended Tags for Documentation Comments.
Punto 2° – Impostare le proprietà del progetto
Per ogni class library della vostra solution dovete abilitare la generazione del file XML di documentazione; per farlo andate nella finestra delle proprietà e spuntate la voce “XML documentation file”, come mostrato qui sotto:
Se abilitate questa opzione, in fase di build, Visual Studio oltre ai file compilati genererà un file XML di documentazione per il progetto.
E’ probabile che vi troviate una serie di “warning” relativi a commenti che non avete inserito o che avete scritto male; a tal proposito, se volte che i vari “warning” per i commenti assenti non vengano visualizzati, potete inserire il codice 1591 nello spazio “Suppress warnings” (come mostrato nell’immagine precedente).
Se avete una solution corposa e volete che in fase di build tutti i file di documentazione generati vengano copiati in un’unica cartella, potete sfruttare i build events. Per la precisione potete inserire nel post-build event delle vostre class library una roba del genere:
dove nel file distributionXML.cmd saranno semplicemente scritte queste istruzioni:
@echo off
copy %1 %2..\XMLDocs /y
In questo modo tutti i file verranno convogliati in una directory, che nell’esempio è stata chiamata “XMLDocs”; come mostrato di seguito:
(chiaramente questo trucchetto può essere sfruttato anche per concentrare in un’unica cartella tutte le dll prodotte dalle class library della soluzione).
Punto 3° – Generare la documentazione
Ora che abbiamo le dll ed i files XML possiamo produrre la nostra documentazione. Per farlo mi sono affidato a Sandcastle, un potente “documentation compiler” distribuito da Microsoft su CodePlex.
- qui potete scaricare il compiler: sandcastle.codeplex.com
- e qui potete scaricare l’help file builder: shfb.codeplex.com
Una volta installati entrambi i componenti, avviate la Sandcastle Help File Builder GUI, aggiungete le dll e i relativi file XML di documentazione e scegliete i settaggi che preferite. Una roba come questa, per capirci…
ci siamo, a questo punto non resta che fare la build della documentazione per ottenere un bel file chm come questo…
Utile, semplice e chiaro…tutto ciò che ci si aspetta da una buona documentazione.
Bene, grossomodo penso di aver detto tutto il necessario…non resta che documentare.
blog comments powered by Disqus
