VB.DOC: XML-Kommentare für VB .NET

Inhalt  

In diese Ausgabe der zweiwöchentlich erscheinenden Kolumne auf ActiveVB.de geht es mehr oder weniger um VB.NET, den vieldiskutierten Nachfolger von VB6. Der größte Konkurrent von VB.NET ist C#, eine völlig neue Sprache von Microsoft, die unter der Leitung des Chefarchitekten Anders Hejlsberg entstanden ist, welcher auch schon Delphi und Pascal entworfen hatte. Viele VB6 Programmierer ziehen in Betracht beim Umstieg auf .NET auf C# umzusteigen, da bei dem immensen Lernaufwand eine Sprachumstellung auch nicht mehr so arg ins Gewicht fällt und C# einige Vorzüge bietet:

• Operatorüberladung
• klarere Syntax
• XML-Kommentare
• .NET Sprache erster Wahl

Einen Punkt aus dieser Liste will ich herausgreifen und näher erläutern: die XML-Kommentare. XML-Kommentare bieten die Möglichkeit strukturierte Kommentare in den Quellcode aufzunehmen und daraus eine Projektdokumentation zu generieren:

///<summary>
/// Eine Klasse für mathematische Operationen
///</summary>
public class Math
{
    ///<summary>
    /// Addiert zwei Zahlen
    ///</summary>
    ///<returns>
    /// Returniert die Summe der beiden Zahlen
    ///</returns>
    ///<param name="a">Der erste Summand</param>
    ///<param name="b">Der zweite Summand</param>
    public long Add(int a, int b)
    {
        return a + b;
    }
}

Listing 1: Ein Beispiel

Wie man sieht, kann man mit den XML-Kommentaren unter anderem die Funktion, den Rückgabewert und die Parameter einer Subroutine dokumentieren. Im Gegensatz zu normalen Kommentaren müssen XML-Kommentare durch drei Schrägstriche in Folge ("///") statt nur durch zwei Schrägstriche eingeleitet werden.

Schön, XML-Kommentare hätten wir in dieser Form auch schon in QBasic schreiben können, wo ist der Fortschritt ? Der C#-Compiler generiert aus diesen Kommentaren eine einzige XML-Datei sofern der Parameter /doc:dateiname beim Aufruf mit angegeben wird:

csc /target:library /out:mathcs.dll /doc:matchcs.xml math.cs

Diese Datei enthält sämtliche Kommentare sowie einige Metadaten:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>math</name>
    </assembly>
    <members>
        <member name="T:Math">
            <summary>
             Eine Klasse für mathematische Operationen
            </summary>
        </member>
        <member name="M:Math.Add(System.Int32,System.Int32)">
            <summary>
             Addiert zwei Zahlen
            </summary>
            <returns>
             Returniert die Summe der beiden Zahlen
            </returns>
            <param name="a">Der erste Summand</param>
            <param name="b">Der zweite Summand</param>
        </member>
    </members>
</doc>

Listing 2

Jetzt kommt NDoc ins Spiel, ein Programm welches diese Informationen zu einer gut lesbaren Dokumentation aufbereitet. NDoc ist ein freies Programm (GPL), einen Downloadlink finden Sie am Ende dieser Kolumne. Die Installation von NDoc gestaltet sich denkbar einfach, entpacken sie einfach das ZIP-Archiv in ein Verzeichnis Ihrer Wahl. Nach dem Start des Tools werden Sie diese Oberfläche vor sich sehen:

Fügen Sie nun mit einem Klick auf Add das Assembly Mathcs.dll samt der zugehörigen XML-Datei zur Liste der zu dokumentierenden Assemblies hinzu. Unterhalb dieser Liste finden sie ein Eigenschaftsfenster, die Optionen hier sollten selbsterklärend sein. Ein Klick auf Documentation | Build und NDoc beginnt mit der Arbeit. Mittels XSLT transformiert NDoc die XML-Datei zu HTML, anschließend wirft es den HTML-Help Compiler an, dieser erstellt die *.chm Datei. Nach einem Klick auf Documentation | View können Sie das Ergebnis bewundern. Nicht schlecht, oder ?

Jetzt werden Sie sich nur noch fragen, weshalb ich Ihnen, als VB.NET Programmierer Programmierer, das alles erzähle, schließlich sind XML-Kommentare doch kein Bestandteil von VB.NET. Nun, es gibt auch hier ein OpenSource Programm welches diese Lücke schließt: VB.DOC.

VB.DOC übernimmt die Arbeit des C#-Compilers, sprich das Erzeugen der XML-Datei welche als Grundlage für NDoc dient. Doch eins nach dem anderen, zuerst wird der obige C#-Code nach VB.NET portiert ...

'<summary>
'Eine Klasse für mathematische Operationen
'</summary>
Public Class Math

    '<summary>
    ' Addiert zwei Zahlen
    '</summary>
    '<returns>
    ' Returniert die Summe der beiden Zahlen
    '</returns>
    '<param name="a">Der erste Summand</param>
    '<param name="b">Der zweite Summand</param>
    Public Function Add(a As Integer, b As Integer) As Long
        Return a + b
    End Function
End Class

Listing 3

... und kompiliert: vbc /target:library /out mathvb.dll

Nach dem Start von VB.DOC werden die notwendigen Einstellungen vorgenommen, d.h. das Assembly wird eingetragen, der Dateiname für die XML-Datei wird angegeben und die Quellcodedateien (in diesem Fall ist es nur eine) werden zur Liste hinzugefügt.

Zu guter Letzt startet ein Klick auf den Button rechts unten den Vorgang. Wenn alles gut gegangen ist, finden Sie dann eine XML-Datei, die sich von derjenigen die der C#-Compiler erstellt hat, nicht unterscheiden sollte. Wie es jetzt weitergeht, können Sie sich bestimmt schon denken: NDoc wird gestartet. Die weiteren Schritte sind identisch mit der geschilderten Arbeitsweise für C#.

Es gibt natürlich nicht nur die im Beispiel verwendeten Tags, eine Übersicht finden Sie hier (.NET Framework SDK vorausgesetzt): Link zu ms-help Seite

Fazit

XML-Kommentare sind über Umwege auch in VB.NET verfügbar. Und es gibt gute Nachrichten aus dem Hause Microsoft: in die nächste Version von VB.NET werden XML-Kommentare integriert, VB.DOC wird dadurch überflüssig.

Links

VB.DOC
NDoc

Beispieldownload

Die Beispiel Codes als Datei 

Ihre Meinung  

Falls Sie Fragen zu diesem Artikel haben oder Ihre Erfahrung mit anderen Nutzern austauschen möchten, dann teilen Sie uns diese bitte in einem der unten vorhandenen Themen oder über einen neuen Beitrag mit. Hierzu können sie einfach einen Beitrag in einem zum Thema passenden Forum anlegen, welcher automatisch mit dieser Seite verknüpft wird.

VB6 Forum .NET Forum