Moduler>Dokumentasjon

Dokumentasjon

Hva

Dokumentasjon av programkode

Dokumentasjon av programkode er mange forskjellige ting. Vi snakker om kravspesifikasjoner på forskejllige nivårer, UML-diagrammer osv. Det vi skal sette fokus på her er de kommentarene som ligger direkte i kodefilene. Slike kommentarer faller i to hovedgrupper:

De kommentarene vi skriver for oss selv (eller kollegaer som jobber i samme prosjekt). Formen på disse kommentarene er direkte og oftest ikke underlagt noen formelle krav. Ofte er volumet av kommentarer større enn volumet av koden. Slike kommentarer er beregnet på den eller de som skal inn og endre kodedetaljer. Den koden jeg skriver er full av kommentaer av typen: "this can be simplified", "rememeber to...", "this algoritme relies on the fact that..", "remember the original value". Disse kommentarene pakker vi inn i de vanlige kommentarparentesene, /* .. */ eller //.
De kommentarene vi skriver for at våre programmoduler skal kunne brukes av andre (eller oss selv) uten at vi trenger gå inn i detaljene i en metode eller en klasse. Det er disse vi skal se nærmere på.

De som er kjent med java og JavaDoc vil finne helt tilsvarende mekanismer for C# under .Net. Vi setter inn tag-er i kommentarer i koden og disse tagene gjenkjennes og organiseres av en dokumentasjonsmotor. I C# kan en slik "formell" kommentar se slik ut:

/// <summary>
/// The main form for the application. This form handles all userinput.
/// </summary>

De 3 slashene (i motsetning til de vanlige 2) indikerer at dette er en interessant kommentar for dokumentasjonsmotoren, og summary er en tag som denne motoren kjenner. Det finnes mange andre slike tagger, se nedenfor.

NDoc

I Visual Studio for .Net 2005 er den automatiske dokumentasjonskommandoen fjernet fra Tools - menyen. Jeg vet ikke om den dukker opp igjen, men alternativet er ganske bra: NDoc. NDoc er et program som lager dokumentasjon i mange forskjellige formater, og kan kjøres som en frittstående applikasjon med GUI eller fra kommandolinja. Det siste tillater også at vi automatiserer dokumentasjons jobben ved å kjøre NDoc som en "post build event" fra Visual Studio, se Project | (ditt prosject)Properties...,Build Events.

NDoc jobber på den måten at den tar to filer som input:

En assembly fil, f.eks. en .exe -fil.
En XML-fil som vi kan be Visual Studio å generere når en assembly bygges. Se menyen Project | (ditt prosject)Properties..., Build og kryss av på XML-documentation file.

I skrivende stund (november 2005) er ikke NDoc (versjon 1.3.1) tilpasset .Net versjon 2. Vi må gjøre noen fixer for å få den til å lese og dokumentere assemblies som er laget for versjon 2 :

Last ned og installer NDoc fra: http://ndoc.sourceforge.net/
Lag en fil som ser slik ut, version er den du finner dersom du sjekker About- menyen i Visual Studio:
```
    <configuration>
      <startup>
         <supportedRuntime version="v2.0.50727" />
      </startup>
    </configuration>
    
```
Lagre den som NDocGui.exe.config i samme katalog som NDocGui.exe.
Last ned fila: MsdnWinFX.zip fra http://www.muschenetz.com/projects/msdnwinfx/
Pakk ut NDoc.Documenter.MsdnWinFX.dll og plasser den i samme katalog som NDocGui.exe

Følg med på NDoc's hjemmesider. Det er vel grunn til å tro at en oppdatert versjon er like rundt hjørnet.

Merking av koden

Det er 2 sett av tagger å forholde seg til:

de taggene som er beskrevet av Microsoft og som i tidligere versjoner av Visual Studio ble brukt av VisualStudios egen dokumentasjonsmotor. Disse er beskrevet her: Recommanded tags for Documentation
De taggene som NDoc kan benytte. Microsofts tagger er et ekte (?) subset av disse. NDocs dokumentasjon beskriver de aktuelle taggene. Du finner dem også her: Tags supported by NDoc

Det betyr at dersom vi venner oss til å bruke alle NDocs markeringstagger så vil vi sannsynligvis få problemer med en eventuell ny documentasjonsgenerator i Visual Studio.

Referanser

NDoc: ndoc.sourceforge.net/

Verson 2 beta fix for NDoc: www.muschenetz.com/projects/msdnwinfx/

Microsofts anbefalinger: Recommanded tags for Documentation

Prosjektet Norge med dokumentert kode og NDoc prosjektfil: norgedoc.zip

Vedlikehold

B.Stenseth, november 2005

(Velkommen) Moduler>Dokumentasjon (Kodetesting)