Das KDevelop-Programmierhandbuch: Leitfaden zur C++-Anwendungsentwicklung fr das K Desktop Environment (KDE) mit Hilfe der KDevelop-IDE in der Version 1.2 | ||
---|---|---|
Zurück | Kapitel 10. Klassendokumentation mit KDoc | Vor |
So wie KDevelop Ihnen alle mglichen Hilfsmittel zum automatischen Erstellen von Code an die Hand gibt, bietet es Ihnen auch die Mglichkeit, die passende Dokumentation generisch zu erstellen. Wann auch immer Sie den Klassengenerator ber "Projekt"-"Neue Klasse..." aufrufen, sollten Sie im Dokumentationsfeld einen beschreibenden Hilfetext einfgen. Dieser erscheint im zugehrigen Headerfile als erluternder Kommentar.
Wenn Sie die Klasse ber das Kontextmen mit neuen Memberfunktionen und Attributen ausstatten, sollten Sie jeweils auch das zugehrige Dokumentationsfeld ausfllen.
Mglicherweise weisen Sie dem Schreiben von Dokumentation als Bestandteil des Entwicklungsprozesses gar keinen so groen Stellenwert zu. Bedenken Sie jedoch, dass -- je weiter Ihr Projekt wchst und je mehr Leute daran beteiligt sind -- eine vernnftige Klassendokumentation sehr viel Zeit spart. Wenn Entwickler aus dem Methodennamen erraten mssen, was die Methode tut, werden Missverstndnisse wahrscheinlich. Im schlimmsten Fall macht die Methode eben nicht das, was der Entwickler erwartet hat. Daher sollten Sie Ihre Dokumentation nicht vernachlssigen und so oft wie mglich aktualisieren.
Behalten Sie dabei im Hinterkopf, dass die Dokumentationsdateien NICHT im Projekt abgespeichert werden und auch keine Internationalisierungsuntersttzung enthalten. Halten Sie smtliche API-Dokumentation daher in englischer Sprache. So ermglichen Sie es auch internationalen Entwicklerteams, an und mit Ihren Quelltexten zu arbeiten.
Wenn Sie einem Headerfile von Hand Kommentare hinzu fgen, die in die Dokumentation eingehen sollen, so platzieren Sie sie wie einen gewhnlichen C-Kommentar oberhalb der Methode oder Klasse -- mit einer Ausnahme: Die erste Zeile muss mit einem Schrgstrich und zwei Sternchen beginnen.
Ein Beispiel:
/** enables menuentries/toolbar items */ void enableCommand(int id_); |