Dokumentationskommentare in C++

Jede definierte Entität sollte auch dokumentiert werden. In dieser Lektion werden die Grundlage der Dokumentation im Doxygen -Format beschrieben. Diese Form der Dokumentation kann so auch verwendet werden, wenn das Programm Doxygen nicht zur Verfügung steht. Doxygen erlaubt es, aus einer mit Dokumentation angereicherten Datei automatisch Dokumentationsdateien zu erstellen.

Solche Kommentare werden auch als Dokumentationskommentare (documentation comments , doc comments ) bezeichnet. Alle anderen Kommentare kann man auch als Implementationskommentare (implementation comments ) ansehen, da sie sich mit Aspekten der Implementation beschäftigen sollten. Diese Unterscheidung und die Festlegung zur Schreibweise von Dokumentationskommentaren wird allerdings nicht durch die Programmiersprache C festgelegt, sondern stellt eine zusätzliche Empfehlung dar.

Kurzbeschreibungen

Direkt vor eine Definition kann ein einzeiliger Kommentar geschrieben werden, der die definierte Entität kurz beschreibt. Wird ein einzeiliger Kommentar mit drei Schrägstrichen "///" eingeleitet, ist er für Doxygen als Dokumentationskommentar gekennzeichnet.

Normalerweise wird ein Dokumentationskommentar direkt vor das zu Dokumentierende geschrieben. So finden sich in dem Beispielprogramm "kuckuck3d.c" Dokumentationskommentare vor jeder Funktionsdefinition.

kuckuck3d.c

#include <iostream> 
#include <ostream>

/// Kehrreim des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben 
static void kehrreim() 
{ printf( "Sim sa la dim, bam ba,\n" ); 
  printf( "Sa la du, sa la dim -\n" ); }

/// Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben 
int main() 
{ // Kann man das nicht noch verkuerzen? 
  { printf( "Auf einem Baum ein Kuckuck, -\n" );   kehrreim(); 
    printf( "Auf einem Baum ein Kuckuck sass.\n" ); } 
  { printf( "Da kam ein junger Jaeger, -\n" );     kehrreim(); 
    printf( "Da kam ein junger Jaegersmann.\n" ); } 
  { printf( "Der schoss den armen Kuckuck, -\n" ); kehrreim(); 
    printf( "Der schoss den armen Kuckuck tot.\n" ); }}

Das Werkzeug Doxygen erlaubt es, Dokumentationsdateien automatisch aus einer wie beschrieben mit Dokumentationskommentaren angereicherten Quelldatei zu erzeugen. Dieses Werkzeug kann für einige verbreitete Betriebssysteme durch Datenfernübertragung leicht beschafft und installiert werden und darf in gewissem Rahmen kostenlos verwendet werden. Doxygen bietet noch mehr Möglichkeiten als hier beschrieben werden—In dieser Lektion werden nur einfache Beispiele der Verwendung vorgestellt.

Doxygen benötigt eine Konfigurationsdatei "Doxyfile", in der die Einstellungen gespeichert werden. Diese kann mit der Option "-g" (im Projektverzeichnis mit der Quelldatei) erzeugt werden.

Konsole [Ausschnitt, gekuerzt]

doxygen -g

Configuration file `Doxyfile' created. 
Now edit the configuration file and enter 
  doxygen Doxyfile 
to generate the documentation for your project

In der Konfigurationsdatei muß die Option "EXTRACT_ALL", die festlegt, daß alle in Frage kommenden Bestandteile des Quelltextes dokumentiert werden sollen, auf den Wert "YES" gesetzt werden. Die Sprache der Ausgabe kann als Deutsch ("German") festgelegt werden. Eine weitere Einstellung sorgt fur eine an C angepaßt Ausgabe.

Doxyfile [Ausschnitte, alter Zustand]

OUTPUT_LANGUAGE        = English 
EXTRACT_ALL            = NO 
OPTIMIZE_OUTPUT_FOR_C  = NO

Doxyfile [Ausschnitte, neuer Zustand]

OUTPUT_LANGUAGE        = German 
EXTRACT_ALL            = YES 
OPTIMIZE_OUTPUT_FOR_C  = YES

Falls sich im Verzeichnis nur die zu dokumentierende Datei befindet, dann kann Doxygen nun ohne weitere Einstellungen oder Argumente aufgerufen werden. Es sucht dann nach Quelldateien.

Konsole [Ausschnitt, gekuerzt]

doxygen

Searching for include files... 
Reading input files... 
Preprocessing kuckuck3d.c... 
Parsing file kuckuck3d.c... 
Generating index page... 
Generating file documentation... 
Generating style sheet...

Doxygen erzeugt unter anderem eine HTML -Datei "kuckuck3d_8c.html" mit der gewünschten Dokumentation.

kuckuck3d.c File Reference [Dokumentation, Ausschnitt, gekuerzt]

Funktionen 
  int  main ()  
    Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.

Man beachte, daß die Dokumentation keine Beschreibung der Methode "kehrreim" enthält, obwohl ihr ein Dokumentationskommentar direkt vorangestellt wurde. Das liegt daran, daß diese Methode nicht öffentlich ist (sie wurde mit dem Schlüsselwort "static" definiert) und daher nicht zur Schnittstelle, also zu den nach außen sichtbaren (von außen aufrufbaren) Funktionen, der Quelldatei gehört. Da diese Entität nicht von außerhalb der Datei verwendet werden kann, braucht ihre Bedeutung auch nicht in der Dokumentation beschrieben zu werden.

Auch der Kommentar "// Kann man das nicht noch verkuerzen?" wird nicht in die Dokumentation aufgenommen, weil er nicht als Dokumentationskommentar gekennzeichnet ist. Dieser Kommentar betrifft ja auch nicht die Schnittstelle der Funktion, sondern ihre Implementation.

Detailierte Beschreibung

Ein Dokumentationskommentar kann auch mit "/**" eingeleitet werden, wie in dem Programm "kuckuck3d1.c". Solch ein Dokumentationskommentar gilt dann als detailierte Beschreibung der Entität.

Es ist auch möglich. innerhalb eines mehrzeiligen Kommentars die Kurzbeschreibung mit dem Kommando "\brief" einzuleiten, die dann mit einer Leerzeile beendet werden muß, auf die der detaillierte Kommentar folgen kann.

Wenn ein Kommentar sich auf die ganze Datei beziehen soll, so muß dieser mit dem Kommando "\file" und dem Dateinamen eingeleitet werden.

Das Programmbeispiel "kuckuck3d1.c" zeigt Beispiele der zuletzt beschriebenen Möglichkeiten.

kuckuck3d1.c

/** \file kuckuck3d1.c 
\brief Kehrreim des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben. 
 
Dieses Programm gibt die ersten drei Strophen des Liedes 
"Auf einem Baum ein Kuckuck sass" aus.  */

#include <iostream> 
#include <ostream>

/// \brief Kehrreim des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben. 
/// 
/// Diese Funktion gibt den gesamten Kehrreim des  
/// bekannten Liedes "Auf einem Baum ein Kuckuck sass" aus.

static void kehrreim() 
{ printf( "Sim sa la dim, bam ba,\n" ); 
  printf( "Sa la du, sa la dim -\n" ); }

/// Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben. 
/** Diese Funktion gibt die ersten drei Strophen des Liedes 
"Auf einem Baum ein Kuckuck sass" aus. */

int main() 
{ // Kann man das nicht noch verkuerzen? 
  { printf( "Auf einem Baum ein Kuckuck, -\n" );   kehrreim(); 
    printf( "Auf einem Baum ein Kuckuck sass.\n" ); } 
  { printf( "Da kam ein junger Jaeger, -\n" );     kehrreim(); 
    printf( "Da kam ein junger Jaegersmann.\n" ); } 
  { printf( "Der schoss den armen Kuckuck, -\n" ); kehrreim(); 
    printf( "Der schoss den armen Kuckuck tot.\n" ); }}

kuckuck3d1.c File Reference [Doxygen-Ausgabe, gekuerzt]

Kehrreim des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.

Funktionen

   int  main () 
     Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.

Ausfuehrliche Beschreibung

   Kehrreim des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.

   Dieses Programm gibt die ersten drei Strophen des Liedes "Auf einem 
   Baum ein Kuckuck sass" aus.

Dokumentation der Funktionen

   int main()

   Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.

   Diese Funktion gibt die ersten drei Strophen des Liedes "Auf einem 
   Baum ein Kuckuck sass" aus.

Erzeugt am Wed Dec 25 23:22:39 2002 von Doxygen 1.3

/** \brief append braces to buffer

\details ...

\param buf pointer to buffer with text with braces

\param bufsiz size of the buffer

\param end append at this position

\param count number of closing braces to be appended

\return nonzero to indicate an error



 */



int fill

( char * const buf,

  size_t const bufsiz,

  char * const end,

  size_t const count )

{ char * p = end;

  for( int i = count; i--; )

  { if( p - buf >= bufsiz - 1 )return 1;

    *p++ = '}'; }

  if( p - buf >= bufsiz )return 2;

  *p = 0;

  return 0; }