NDoc

pubblicato il 02/06/2006

Come riportato nella homepage del progetto, NDoc genera la documentazione per le librerie di classi partendo dagli assembly .NET compilati e dai file XML di documentazione generati dal compilatore C# o da un add-in di Visual Studio 2003per Viosual Basic, VbCommenter. Occorre dire che il progetto NDoc è praticamente abbandonato dal febbraio 2005 in quanto, con l'introduzione del nuovo Visual Studio, anche il compilatore Visual Basic è in grado di generare la documentazione XML necessaria.

Il programma presenta un unica videata, divisa orizzontalmente in tre grandi aree: in alto la zona che consente di selezionare gli assembly per i quali verrà generata la documentazione, al centro la zona che consente di selezionare le opzioni per la generazione, in basso l'output che verrà generato dal programma man mano che procede nella generazione; sopra a tutto ciò, l'ormai abituale area destinata al menu e alla toolbar.

L'uso è molto intuitivo: come prima cosa occorre scegliere gli assembly per i quali si desisdera generare la documentazione, premendo il pulsante Add nella parte superiore della form; tramite il pulsante Namespace Summaries è possibile aggiungere una vera e propria introduzione alle namespace presenti negli assembly.

Fatto ciò si passa alla scelta delle numerossissime opzioni; per motivi di tempo e spazio discuterò qui soltanto quelle che (a mio insindacabile giudizio) ritengo le più importanti.

CopyrightText: il testo del copyright, qualcosa tipo "{$ .CopyRight $}"

CopyrightHref: il link ad un URL da visitare facendo click sul CopyrightText

FeedbackEmailAddress: l'indirizzo email per i feedback degli utenti

HtmlHelpName: il nome sia del progetto NDoc, sia delò fiole di help che verrà generato.

OutputDirectory: la directory dove verrà generato il file di help da distribuire.

CleanIntermediates: indica s i file temporanei debbano essere cancellati una volta generato l'help in linea (io di solito lo imposto a True)

OutputTarget: il tipo di help che deve essere generato: può essere HTML Help (la mia scelta), Web, HTML Help and Web (il default).

Preliminary: indica se la documentazione debba essere rimarcata come preliminare con la scritta [This is preliminary documentation and subject to change.]

SdkLinksOnWeb: curiosamente, impostando questa opzione a True, il programma va in crash, ma non escludo che sia colpa di qualche configurazione del mio computer.

Title: facile: il titolo della documentazione che verrà generata.

LangID: imposta il codice della lingua nella quale è scritta la documentazione; tuttavia anche impostando la lingua italiana, le scritte predefinite appariranno in inglese.

RootPageContainsNamespaces: se impostata a True, la pagina iniziale conterrà i link alle varie namespaces presenti, altrimenti la pagina iniziale sarà la pagina iniziale della prima namespace, a meno che non si imposti la proprietà RootPageFileName.

RootPageFileName: imposta il file html specificato come pagiona iniziale della documentazione.

ShowMissingDocumentation: in questa sezione sono riportati una serie di parametri (Params, Remarks, Returns, Summaries, Values) che indicano se l'assenza di documentazione per ciascuno di questi elementi debba essere rimarcata con una scritta del tipo Missing <params|remarks|returns|summaries|values> documentation for XXX. Personalmente preferisco impostarle tutte a True per rendermi conto della documentazione che resta ancora da scrivere.

Per quanto riguarda le altre opzioni, personalmente accetto i valori di default.

Una volta impostate le opzioni che ci interessano, possiamo generare la documentazione: dal menu Documentation | Build, oppure clickando sul quinto pulsante da sinistra della toolbar, oppure premenendo SHIFT+CTRL+B, verrà avviata la generazione e compilazione della documentazione; nel caso dell'Help file, possiamo anche vedere il risultato generato clickando sull'ultimo pulsante della toolbar.