Visual Studio XML Documentation

Technorati-Tags: Programming,Tools,VisualStudio,Documentation

 

Heute mal etwas was mit Softwareentwicklung zu tun hat. Visual Studio hat ja, ich glaube seit Version 2002, eine Möglichkeit eingebaut Sourcecode direkt zu dokumentieren, so wie man es von javadoc, oder auch Doxygen her gewohnt ist. Das ist einmal was nettes, vorallem weil man sich dann das mühsame nachträgliche Dokumentieren des Sourcecods erspart, und man sollte ja seinen Code dokumentieren ;-).

Aber das was dabei raus kommt ist weniger fancy als das was javadoc oder Doxygen ausspuckt, alles was man bekommt ist ein einziges XML File wo alle Klassen, ihre Methoden und sonstiges vermerkt ist, keine schöne HTML Dokumentation gar nichts. Ist ja super wenn man alles dokumentieren kann, mit einer eigentlich recht guten Syntax und gute Unterstützung von Visual Studio selbst, nur ist halt dann trotzdem der Sinn dahinter dass man eben diese Dokumentation auch später dem Nächsten geben kann, ohne dass er den Source dazu braucht. Das XML File ist zwar sauber genug aufgebaut dass man ein Postprocessing damit machen kann, aber dafür muss man erst wieder ein externes Tool entweder schreiben, oder benutzen, oder gleich Doxygen die ganze Arbeit machen lassen und auf das XML - File, das Visual Studio (eigentlich der jeweilige Compiler, ist IMHO auch spannend, aber bei näherem Nachdenken doch logisch) liefert.

Noch ein Wort zum Aufbau des XML - Files das Studio produziert:
Es ist zwar schön ersichtlich, was eine Klasse, was eine Methode, was ein Field oder eine Property ist, es wäre allerdings (für einen Postprocessor) durchaus hilfreich zu wissen welchen Accessmodifier (public, protected, private static usw.) das jeweilie Element hat, fällt scheinbar unter: "Gute Idee, aber nicht zu Ende gedacht".

Als Beispiel hier eine kleine simple Klasse ToDocument mit ihrer Sourcelevel Dokumentation:


/// <summary>
/// This is a fanzy class that does a lot of things
/// </summary>
public class ToDocument
{
/// <summary>
/// A fancy method
/// </summary>
/// <param name="fnacyParam">A fanzy param</param>
/// <returns>a fancy value</returns>
/// <exception cref="Exception">On a fancy condition</exception>
public int DoFanzyThings(int fnacyParam)
{
return (0);
}

/// <summary>
/// A fancy member
/// </summary>
private int fancyMember = 0;
}


Und hier das was an "Dokumentation" ausgespuckt wird:

<?xml version="1.0"?>
<doc>
<assembly>
<name>DocTest</name>
</assembly>
<members>
<member name="T:DocTest.ToDocument">
<summary>
This is a fanzy class that does a lot of things
</summary>
</member>
<member name="M:DocTest.ToDocument.DoFanzyThings(System.Int32)">
<summary>
A fancy method
</summary>
<param name="fnacyParam">A fanzy param</param>
<returns>a fancy value</returns>
<exception cref="T:System.Exception">On a fancy condition</exception>
</member>
<member name="F:DocTest.ToDocument.fancyMember">
<summary>
A fancy member
</summary>
</member>
</members>
</doc>

Das XML sieht ein wenig anders aus als jenes das Studio generiert, aber nur der Einzug von vorne ist anders, der Inhalt ist der selbe (Man könnte BlogSpot vielleicht korrektes Einbinden von Dateien beibringen ;-) )

Also muss man auch bei Visual Studio weiterhin auf Doxygen zurück greifen um vernünftige Sourcedokumentation zu erhalten, da Doxygen die Dokumentationssyntax von Visual Studio mitlerweile auch beherscht :-)