Die Inline-Dokumentation ist wichtig, da aus ihr mit Doxygens Hilfe eine übersichtliche Code-Dokumentation erstellt wird. Das erspart den Programmierern die viele Arbeit, alles extra hier im Wiki zu dokumentieren und ermöglicht es auf der anderen Seite, einen schnellen Überblick über eine Klasse, ihre Methoden usw. zu bekommen.
Hier werden Konventionen für die Inline-Dokumentation vorgestellt, die dann von allen Programmierern befolgt werden sollten.
Überall, wo spezielle Elemente dokumentiert werden, sollte die Dokumentation direkt vor der Deklaration platziert werden, ohne weitere Leerzeilen.
Da Doxygen sehr stark klassenbasiert arbeitet, stellt der Dateiheader gleichzeitig den Klassenheader da. In Dateien ohne Klassen wird dieser einfach als Dateiheader übernommen.
/** * Kurze Beschreibung der Klasse/Datei. * * Lange Beschreibung der Klasse/Datei. * * @author DSAo-Md * @author http://www.gnu.org/licenses/gpl-3.0.html GNU Public License * @version SVN: \$Id$ */ class Blubb_Bla { }
Ohne große Worte:
/** * type, kurze Beschreibung der Eigenschaft. * * Längere Beschreibung der Eigenschaft. */ private $_property = null;
Da Doxygen keine Datentypen für Parameter unterstützt, müssen wir uns anders behelfen:
/** * Kurze Beschreibung. * * Detailliertere Beschreibung. * * @param $paramName type, Beschreibung. * @return type, Beschreibung */ public function bla($paramName)
Werden nur mit einfachen Kommentaren versehen. Der Typ ist ggf. am Anfang abgetrennt durch ein Komma anzugeben.
Wurden bei der Inline-Dokumentation syntaktische Fehler gemacht, werden diese von Doxygen bemängelt. Diese Fehlermeldungen werden in regelmäßigen Abständen aktualisiert und sollten von den Programmierern auch regelmäßig überprüft werden.