Tutti sappiamo che la documentazione delle classi è una delle attività più noiose... Per fortuna GhostDoc consente di velocizzare enormemente questo lavoro. Si tratta di un add-in freeware per Visual Studio che aggiunge il comando Document this al menu contestuale delle finestre dell'editor: facendo clic su di esso, viene generato automaticamente lo stub della documentazione per il metodo, la proprietà, ..., su cui si è fatto clic. Lo schema prodotto comprende il campo summary e le eventuali entry di tipo param e returns, già precompilate, nel caso in cui il metodo prenda dei parametri in ingresso e restituisca un valore.
Ma GhostDoc fa molto più di questo: esso, infatti, è in grado di inferire la descrizione del metodo, nel caso in cui il suo nome rispetti un certo formato. Ad esempio, il metodo
public string GetUserName(int userID)
Viene automaticamente commentato nel modo seguente:
/// <summary>
/// Gets the name of the user.
/// </summary>
/// <param name="userID">The user ID.</param>
/// <returns></returns>
public string GetUserName(int userID)
Certo, questo sistema non è infallibile, ma spesso riesce a generare buoni commenti. Inoltre, utilizzando il comando GhostDoc che viene aggiunto al menu Tools di Visual Studio, è possibile configurare tutti le impostazioni e le regole su cui il programma si basa per creare i commenti.
La potenzialità di GhostDoc non si fermano qui: esso comprende anche lo schema completo della documentazione per i metodi "standard" del .NET, come ad esempio Dispose: in questo caso, facendo clic destro su di esso e selezionando Document this, viene inserito un commento completo di tutte le sue parti, che quindi non richiede ulteriori modifiche. Inoltre, se si creano metodi override, qualora sia disponibile viene automaticamente inserita la documentazione del metodo che si sta ridefinendo. Un'altra caratteristica interessante è che, se si aggiunge un commento con Document this, quindi lo si modifica, eseguendo una seconda volta il comando Document this il testo inserito non viene perso, anzi, se necessario, viene riformattato ed indentato correttamente.
Sul sito dell'autore sono disponibili sia la versione per Visual Studio 2003 sia quella per Visual Studio 2005. Quest'ultima supporta anche Visual Basic .NET (seppure in modo definito sperimentale). Nella sezione delle news della stessa pagina è riportato un avviso secondo cui l'installazione di GhostDoc ha alcuni problemi con Windows Vista. Io l'ho installato su due diversi PC (uno con Vista Business, l'altro con Vista Ultimate) e non ho riscontrato inconvenienti. Ad ogni modo, in caso di necessità è possibile fare riferimento a questo post.
Nel complesso, si tratta di un buon prodotto, tanto che fa parte dei 10 Must-Have Add-Ins suggeriti da Microsoft. C'è però una mancanza abbastanza evidente: il comando Document this non è disponibile per le classi, gli eventi, i delegate e gli elementi di una enumerazione. Non so per quale motivo ci sia questa limitazione, dal momento che il sistema di generazione dei commenti dovrebbe essere uguale a quello che viene applicato per i metodi e le proprietà.