Das K Desktop Environment

10.2. Klassen- und Memberdokumentation hinzufügen

So wie KDevelop Ihnen alle möglichen Hilfsmittel zum automatischen Erstellen von Code an die Hand gibt, bietet es Ihnen auch die Möglichkeit, die passende Dokumentation generisch zu erstellen. Wann auch immer Sie den Klassengenerator über "Projekt"->"Neue Klasse..." aufrufen, sollten Sie im Dokumentationsfeld einen beschreibenden Hilfetext einfügen. Dieser erscheint im zugehörigen Headerfile als erläuternder Kommentar.

Wenn Sie die Klasse über das Kontextmenü mit neuen Memberfunktionen und Attributen ausstatten, sollten Sie jeweils auch das zugehörige Dokumentationsfeld ausfüllen.

Möglicherweise weisen Sie dem Schreiben von Dokumentation als Bestandteil des Entwicklungsprozesses gar keinen so großen Stellenwert zu. Bedenken Sie jedoch, dass -- je weiter Ihr Projekt wächst und je mehr Leute daran beteiligt sind -- eine vernünftige Klassendokumentation sehr viel Zeit spart. Wenn Entwickler aus dem Methodennamen erraten müssen, was die Methode tut, werden Missverständnisse wahrscheinlich. Im schlimmsten Fall macht die Methode eben nicht das, was der Entwickler erwartet hat. Daher sollten Sie Ihre Dokumentation nicht vernachlässigen und so oft wie möglich aktualisieren.

Behalten Sie dabei im Hinterkopf, dass die Dokumentationsdateien NICHT im Projekt abgespeichert werden und auch keine Internationalisierungsunterstützung enthalten. Halten Sie sämtliche API-Dokumentation daher in englischer Sprache. So ermöglichen Sie es auch internationalen Entwicklerteams, an und mit Ihren Quelltexten zu arbeiten.

Wenn Sie einem Headerfile von Hand Kommentare hinzu fügen, die in die Dokumentation eingehen sollen, so platzieren Sie sie wie einen gewöhnlichen C-Kommentar oberhalb der Methode oder Klasse -- mit einer Ausnahme: Die erste Zeile muss mit einem Schrägstrich und zwei Sternchen beginnen.

Ein Beispiel:

   /** enables menuentries/toolbar items
   	*/
   void enableCommand(int id_);