mikrocontroller.net

Forum: PC-Programmierung Kommentierung des Quellcodes fuer Doxygen


Autor: daniel (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Sven P. (haku) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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?

Autor: daniel (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
> 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

Autor: Sven P. (haku) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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 :-)

Autor: yalu (Gast)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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.

Autor: Peter S. (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Sehr nützliche und hilfreiche Erklärung ! Danke.

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.
Hinweis: der ursprüngliche Beitrag ist mehr als 6 Monate alt.
Bitte hier nur auf die ursprüngliche Frage antworten,
für neue Fragen einen neuen Beitrag erstellen.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.