Dokumentasjon
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.