Hallo, Werden die Funktionen in der Header oder in der Sourcedatei dokumentiert? Ich moechte nun mein Projekt implementieren und frage mich, wo ich die Kommentare zu den Funktionen platzieren soll. Status Quo ist, dass ich alle Funktionen doppelt kommentiert habe. Einmal in der Headerdatei und einmal in der Sourcedatei. Nur frage ich mich, ob das nicht ein bisschen unsinnig ist soviel Zeilen Text zu erzeugen, da es immer zweimal dokumentiert ist. Andererseits muss ich nicht jedesmal zwischen den Dateien hin und her wechseln nur um nochmal eine Definition nachzuschauen. Es scheint mir fast so das es im Source angenehmer fuer den Programmierer ist und in der Headerdatei angenehmer fuer den Drittnutzer, welcher schnell einen Ueberblick bekommt. Hat jemand Erfahrung dazu und nicht nur Gedankenspiele und kann mir einen Tipp geben? Gruss daniel
daniel wrote: > Es scheint mir fast so das es im Source angenehmer fuer den > Programmierer ist und in der Headerdatei angenehmer fuer den > Drittnutzer, welcher schnell einen Ueberblick bekommt. Richtig. Wenn du aber schon mit Doxy arbeitest, sollte der Drittnutzer doch in die Doxy-Referenz reingucken und nicht in die Header, oder?
> Wenn du aber schon mit Doxy arbeitest, sollte der Drittnutzer > doch in die Doxy-Referenz reingucken und nicht in die Header, oder? Vielleicht ist es besser eine kleine grobe Referenz in der Headerdatei und den Rest in der Sourcedatei, wobei wieder eben ein bisschen doppelter Text erzeugt wird, aber eben nicht so viel. Dadurch laesst sich die Headerdatei als grobe Referenz nutzen und die Doxy-Referenz als feine und detailierte. Gruss daniel
Doxygen generiert bereits eine grobe Übersicht, die dann mit der detaillierten Beschreibung verlinkt wird. Problem bei der doppelten Tipperei: Es kommt garantiert immer wieder der Zeitpunkt, an dem die beiden Dokumentationen nicht mehr übereinstimmen und du das zu spät bemerkst :-)
Wo die Doxygen-Kommentare hingeschrieben werden, hängt vom Typ der Dokumentation ab, die erstellt werden soll. Die Dokumentation besteht aus Teilen, die sich mit dem Was, und anderen Teilen, die sich mit dem Wie beschäftigen: Was-Dokumentation: - Was tut die Funktion? - Welche Daten gehen in die Funktion hinein, welche kommen heraus? - Wofür steht ein Datentyp, was kann man damit anfangen? - Ergänzende Informationen zur Verwendung der Funktionen und Datenstrukturen - ... Wie-Dokumentation: - Wie ist eine Funktion oder eine Datenstruktur implementiert? - Warum wurde sie so implementiert? - Welche Algorithmen und Programmierkniffe kommen zum Einsatz? - ... 1. API-Dokumentation Sie dokumentiert eine Programmbibliothek und richtet sich an den Anwender dieser Bibliothek, also einen Programmierer auf höherer Ebene. Darin sind alle Funktionen und Datenstrukturen beschrieben, die die Bibliothek dem Anwender zur Verfügung stellt. Soll die Dokumentation kein reines Nachschlagewerk (Referenz) sein, enthält sie zusätzlich übergreifende Informationen, wie z.B. - Informationen über das Zusammenwirken der Funktionen und Datenstrukturen - allgemeine Hinweise zur effektiven Nutzung der Bibliothek - Programmbeispiele, die sich auf mehrere Funktionen oder Datenstrukturen beziehen - usw. Die formale Beschreibung des API besteht aus den C-Deklarationen in den vom Anwender genutzten header-Files. Da zwischen diesen und der textuellen Beschreibung der dem Anwender zur Verfügung gestellten Funktionen und Datenstrukturen eine 1:1-Beziehung besteht, ist es sinnvoll, die textuellen Beschreibungen (also die Doxygen-Kommentare) in dieselben Header-Files zu schreiben. Diese Kommentare enthalten typischerweise nur Was-, aber keine Wie-Informationen. Das Wie ist für den Anwender nur in Ausahmefällen von Interesse, bspw. dann, wenn zwei Funktionen Ähnliches tun, aber unterschiedliche Algorithmen verwenden. Dann kann die Kenntnis der Algorithmen eine Entscheidungshilfe für die Auswahl der für den aktuellen Anwendungsfall bestgeeigneten Funktion sein. Eine Kurzbeschreibung der Algorithmen kommt dann ebenfalls in die Header-Files. Ebenfalls von geringem Interesse für den Anwender sind Hilfsfunktionen und Datenstrukturen, die ausschließlich intern verwendet werden. Diese sollten nicht als C-Code in den vom Anwender verwendeten Header-Files auftauchen und sollten in der API-Dokumentation auch nicht dokumentiert zu werden, da sie eher zur Verwirrung als zum Verständnis beitragen. Die übergreifenden Informationen sollten auch in einer übergeordneten Datei stehen. Man schreibt sie deswegen entweder in das zentrale Header-File der Bibliothek, oder — wenn die Informationen zu umfangreich sind — in eine oder mehrere eigene Dateien, die nur Doxygen-Kommentare enthalten. Bei größeren APIs kann auch eine Hierarchisierung — sowohl der Header-Files als auch der Erläuterungen — in mehreren Ebenen sinnvoll sein. Doxygen bietet auch hier Unterstützung. 2. Entwicklerdokumentation Sie dokumentiert ein Anwendungsprogramm oder eine Programmbibliothek und richtet sich an die aktuellen und zukünftigen Entwickler dieser Software. Der Inhalt ist ähnlich dem der API-Dokumentation, enthält aber außer dem Was auch das Wie, also bspw. die in den Funktionen verwendeten Algorithmen. Die Wie-Dokumentation schreibt man sinnvollerweise dorthin, wo die Algorithmen implementiert sind, nämlich in die C-Files. Wo man die Was-Dokumentation hinschreibt (ob in die Header- oder die C-Files), ist eher Geschmacksache. Für eine reine Entwicklerdokumentation würde ich der leichteren Handhabbarkeit wegen alle Kommentare in die C-Files schreiben (aber siehe "3. Kombinierte Dokumentation"). Für den Entwickler ist natürlich auch die Beschreibung von Interna wichtig, deswegen stehen diese ebenfalls dort, wo die entsprechenden Funktionen und Datentypen deklariert bzw. implementiert sind. Ebenso wie die API-Dokumentation kann auch die Entwicklerdokumentation hierarchisiert werden. 3. Kombinierte Dokumentation Für eine Programmbibliothek möchte man meist zwei Dokumentationen erstellen, eine für die Anwender und eine für die Entwickler der Bibliothek. Es ist bei entsprechender Organisation leicht möglich, aus einem Satz Doxygen-Kommentare sowohl die API- als auch die Entwicklerdokumentation zu erzeugen: Man schreibt dazu das, was den Anwender interessiert, gemäß Abschnitt 1 in die vom Anwender genutzten Header-Files. Die Wie-Dokumentation für den Entwickler kommt in die C-Files und die Was-Dokumentation interner Funktionen oder Datenstrukturen in ausschließlich intern genutzte Header-Files oder (je nach Gechmack) ebenfalls in die C-Files. Je nachdem welcher Dokumentationstyp gewünscht wird, lässt man Doxygen entweder nur über die Anwender-Header-Files oder über alle Quellcode-Files laufen. Dabei ergibt sich die Trennung zwischen den für den jeweiligen Doxygen-Lauf benutzten Dateisätzen aus den Dateinamen (Extensions) oder (besser) aus den Verzeichnissen, in denen die Dateien liegen. Besteht die Dokumentation einer Funktion aus zwei Teilen, nämlich aus dem Was-Teil im Anwender-Header-File und dem Wie-Teil im C-File, kombiniert Doxygen für die Entwicklerdokumentation die beiden Teile so, dass direkt hintereinander zuerst der Header-File-Kommentar und danach der C-File-Kommentar aufgeführt wird, wodurch sich automatisch die richtige Reihenfolge von der Abtstraktion hin zum Detail ergibt. Huch, das ist wieder einmal lang geworden ;-) Ich hoffe, dass trotzdem jemand etwas damit anfangen kann.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.