Un cliente mi e' stato chiesto di realizzare una parte di un nuovo framework, ok, nulla di strano, e come tutte le parti di codice che devono essere condivise da diversi sviluppatori, oltre che dover funzionare (questo dovrebbe essere implicito...) devono essere ben documentate e la documentazione deve essere, ovviamente, sincronizzata con il codice.
Nel tentativo di evitare il doppio lavoro di codificare e, parallelamente, scrivere la relativa documentazione, ho deciso di affidarmi ad un apposito tool, ovvero il ben noto NDoc.
Che dire, ne sono rimasto cosi' entusiata che mi va di consigliarlo (per chi ancora non lo conosce) a tutti coloro che devono documentare il proprio codice.
Basandosi sui commenti xml generati dal compilatore C# e' in grado di generare in maniera facile  e veloce la relativa documentazione in diversi formati (Web, HTML Help v1,HTML v2,Latex,JavaDocs...) il tutto in modo facile ed immediato.
Visto che si basa sui commenti xml, si potrebbe pensare che NDoc non sia utilizzabile dagli sviluppatori VB.NET fino quando la versione 2005, che supportera' i commenti xml, non verra' rilasciata, bene, non e' vero, anche con la versione 2003 gli sviluppatori VB.NET possono documentare il proprio codice come in C# usando questo add-in e utilizzare anche loro NDoc (oltre che avere i commenti nell'intellisense...)
Alcuni dettagli per chi volesse usare NDoc con VB.NET 2003, l'add-in ha qualche piccolo problema nel generare i commenti, quindi se volete usare i tags "" o "" ricordatevi di includere come cref anche i relativi prefissi T:, M:, E: e di dichiarare gli eventi in maniera C# like (delegate e relativo event) altrimenti non verranno correttamente descritti nella documentazione.
Ormai NDoc e' parte integrante del mio Visual Studio, se doveste avere necessita' di questo tipo, provatelo, se ha rimosso la feature Build comment web pages da Visual Studio 2005 e Gunnerson suggerisce l'uso di NDoc un motivo ci sara'...