NDoc

NDoc er et dokumentationsværktøj rettet mod .NET-udviklingsplatformen. NDoc fungerer i høj grad som JavaDoc gør for Java. NDoc muliggør dokumentation for udviklere imellem, og benyttes derfor primært til at give en stringent specifikation af en mængde kodes funktionalitet og grænseflade. NDoc benytter eksterne XML filer som input og sammenholder disse med oversatte assemblies for at give et fuldstændigt billede af den udviklede kode. Opdelingen af kode og dokumentation gør det muligt at skrive (eller flot gennemlæse) dokumentation uden mulighed for at indføre fejl i selve kildekoden. Endvidere er det muligt at skrive, redigere og klargøre dokumentation i forskellige formater uden at skulle oversætte kildekoden på ny.

Brug af værktøjet

NDoc scanner en eller flere .NET assemblies via reflection for at finde informationer som klasser, namespaces etc. Disse informationer sammenholdes med selve dokumentationen som bliver gemt i et specielt XML format. NDoc giver brugeren mulighed for at skjule informationer i dokumentationen selvom de er blevet dokumenterede af en programmør. Derved er det muligt for f.eks. et firma at vedligeholde en fuldstændig dokumentation til intern brug og dele en mere begrænset version til eventuelle kunder og samarbejdspartnere.

XML format

Dette er ikke en fuldstændig gennemgang af de dokumentationsmuligheder NDoc giver, men blot en kort introduktion til tankegangen bag. Følgende er et eksempel på dokumentation i C#, det er dog også muligt at benytte NDoc i andre .NET sprog.

 /// <summary>Min klasse.. Printer Hello Wiki</summary>
 /// <remarks>Jeg har ingen bemærkninger</remarks>
 class MinKlasse {
    
    /// <param name="args">Argument til main. Bliver dog ikke brugt til noget</param>
    /// <returns>Et tal der altid er 1</returns>
    public static int Main(string[] args) {
        System.Console.WriteLine("Hello Wiki");
        return 1;
    }
 }
 

Som det fremgår af eksemplet benyttes /// til at markere at linje skal læses af NDoc. Det er også muligt at holde selve dokumentationen ude af kildekoden ved at lave eksterne referencer:

 /// <include file='mydoc.xml' path='Dokumentation/Klasser[@name="MinKlasse"]/*' />
 class MinKlasse {
    
    public static int Main(string[] args) {
        System.Console.WriteLine("Hello Wiki");
        return 1;
    }
 }
 

Med en dertilhørerende dokumentations xml fil:

 <Dokumentation>
   <Klasser>
      <MinKlasse>
       <summary>Min klasse.. Printer Hello Wiki</summary>
       <remarks>Jeg har ingen bemærkninger</remarks>
      </MinKlasse>
   </Klasser>
 </Dokumentation>

Generering af XML filer

Idet kommentarer i koden bliver fjernet under oversættelse til assemblies er det nødvendigt at hente alle NDoc linjerne fra kildekoden ud i en ekstern xml fil ved eller før kildekoden bliver oversat. Dette kan gøres ved 'out parameteren på Microsoft C# oversætter eller ved brug af VBCommenter for VB.NET. Rettelser til dokumentation bør ikke foretages i den genererede XML fil da disse vil blive overskrevet ved næste oversættelse af kildekoden.

Generering af dokumentation

Det er muligt både at benytte NDoc på kommandolinjen og som en grafisk klient. For større projekter vil det ofte være praktisk at automatisere dokumentationen ved brug af NDoc via kommandolinjen. Visse output formater (se næste afsnit) kræver specielle andre programmer som skal hentes og installeres.

Output formater

NDoc kan generere dokumentationen i flere forskellige formater:

• JavaDoc: JavaDoc er Suns dokumentationsmetode og består af et frameset i HTML.
• LaTeX: Generering af Latex, der derefter kan oversættes til DVI, postscript eller PDF.
• LinearHTML: Simpel HTML struktur.
• MSDN:
• MSDN 2003:
• VS.NET 2003:
• XML:

Eksterne links

• NDoc Code Documentation Generator for .NET

Spire Denne artikel om software er en spire som bør udbygges. Du er velkommen til at hjælpe Wikipedia ved at udvide den.