Doxygen Dokumentation für C# unter Mac OS X erzeugen

Ein Quelltext wird während der Entwicklung gewöhnlich kommentiert. Unter C# bzw. .NET gibt es dafür Kommentare nach einem bestimmen Schema. Über einer Methode könnte ein solcher Kommentar z.B. aussehen:

/// <summary>
/// Distance between a and b.
/// </summary>
/// <param name="a">The first vector.</param>
/// <param name="b">The second vector.</param>

Diese Kommentare kann die freie Software Doxygen auswerten und daraus eine Dokumentation erzeugen. Im Gegensatz zu anderen Lösungen wie Sandcastle ist Doxygen betriebsystemübergreifend verfügbar und kann somit – wie in diesem Beispiel – unter Mac OS X genutzt werden. Im ersten Schritt sollte Doxygen installiert werden. Unter Mac OS X kann dies einfach über MacPorts geschehen:

sudo port install doxygen

Nachdem Doxygen installiert ist, sucht man im Terminal den Ordner des Entwicklungsprojektes heraus und gibt dort ein:

doxygen -g projektname.doxygen

Damit wird eine Standard-Doxygen-Konfiguration erzeugt. In dieser Datei werden nun ein paar Änderungen vorgenommen:

PROJECT_NAME = "Testprojekt"
PROJECT_NUMBER = "Release Candidate 1"
OUTPUT_DIRECTORY = docs
RECURSIVE  = YES

Über den Aufruf:

doxygen projektname.doxygen

kann nun die HTML-Dokumentation des Quelltextes erzeugt erzeugt werden und diese anschließend im Browser genutzt werden.

The Right Way

Bücher über PHP-Entwicklung gibt es wie Sand am Mehr. Bücher an denen man mitarbeiten kann allerdings weniger. Zu dieser Klasse von Büchern gehört PHP – The Right Way, deren Quelltext auf GitHub zu finden ist. In dem Buch geht es dabei nicht nur um die Sprache PHP als solches, sondern auch um die Entwicklungsumgebung, Sicherheit und andere Themen.

Die deutsche Version von PHP - The Right Way.

Die deutsche Version von PHP – The Right Way.

Neben der englischen Originalversion gibt es auch eine ganze Reihe von Übersetzungen. Während es sich bei den Versionen bis zum 10. Juli 2012 noch um eine freie Version unter MIT-Lizenz handelte, wird mittlerweile die deutliche restriktivere Creative Commons Lizenz BY-NC-SA genutzt. Diese schließt eine kommerzielle Nutzung aus. Die offizielle Seite ist unter phptherightway.com zu finden.

Dokumentierte Dateiformate

Bei meiner Arbeit kommt es öfter mal vor das ich Dateiformat XY implementiere. Dabei gibt es dann unterschiedliche Fälle. Der erste Fall ist das Dateiformat gut dokumentiert ist, und es eventuell sogar schon eine freie Bibliothek für das Format in der passenden Programmiersprache gibt. Dieser Fall ist subjektiv leider der seltenste Fall.

Viel häufiger kommt es vor das das Dateiformat gar nicht, bzw. nur lückenhaft dokumentiert ist. Das liegt manchmal daran das der Hersteller es nicht gerne sieht wenn das Format dokumentiert ist, manchmal auch daran das das Format mit der Zeit organisch gewachsen ist. So sitzt man nun als Entwicker da und fängt an die Formate auseinander zunehmen. So schreibt z.B. Photoshop invalide BMP Header und es kostet viel Mühe so etwas herauszufinden. Nach Stunden, manchmal auch erst Tagen hat man dann endlich das entsprechende Format unterstützt.

Und manchmal frage ich mich dabei, ob es anderen Entwicklern genauso geht und überlege wie viel Arbeit man sich ersparen könnte wenn man eine zentrale Anlaufstelle schafft, in welcher Dateiformate (vorzugsweise in deutscher Sprache) dokumentiert werden. Ich stelle mir da ein Wiki unter einer entsprechenden Lizenz vor (z.B. eine CC-BY) und in diesem werden dann die Dateiformate dokumentiert so das zukünftige Entwickler nicht mehr ganz so viel Arbeit haben. Was haltet ihr von einer solchen Idee?