Makro-C-Objekte in Doxygen

Wenn ich meine selbstgestrickten Makros einsetze, um V-Table structs generieren zu lassen und anschließend C-Klassen structs, dann schreibt Doxygen ziemlich wirres Zeug.

Ähnlich ergeht es manch alten COM Projekten in C, die ebenfalls mit Makros arbeiten (die mir ja auch als Inspiration gedient haben).

Wie bekommt man also eine Doxygen-konforme Lösung hin?

Wie Microsoft’s COM in reinem C Code aussah, hat Raymond Chan bereits super dokumentiert

Im GATE Projekt beginnt alles mit dem “gate_object” Interface und das wird aus “ähnlichen” Makros zusammengebaut. Alle Ableitungen müssen dabei das Interface der Basisklassen nochmals exakt nachstellen, damit die entstehende V-Table “kompatibel” bleibt:

 GATE_INTERFACE(gate_object)
 {
   GATE_METHOD0(char const*, get_interface_name);
   GATE_METHOD0(void,        release);
   GATE_METHOD0(int,         retain);
 };
 
 GATE_INTERFACE(gate_cloneable)
 {
  /* extends: gate_object */
  GATE_METHOD0(char const*, get_interface_name);
  GATE_METHOD0(void,        release);
  GATE_METHOD0(int,         retain);

  /* clonable methods: */
  GATE_METHOD1(gate_result_t, clone, gate_cloneable_t** clone);
};

Daraus wird für ein gate_cloneable Interface in etwa folgender Code generiert:

 typedef struct
 {
   char const* (*get_interface_name)(void* thisptr);
   void        (*release)           (void* thisptr);
   int         (*retain)            (void* thisptr);
 
   gate_result_t (*clone)(void* thisptr, gate_cloneable_t** clone);
 } gate_cloneable_vtbl;
 
typedef struct
{
  gate_cloneable_vtbl const* vtbl;
} gate_cloneable_t;

Doxygen kann jedoch die etwas komplexeren Makros im Hintergrund leider nicht alle Auflösen und somit kann ich leider nicht einfach vor GATE_INTERFACE() oder vor GATE_METHOD() meine Doku schreiben.

Lösung: Pseudo-Klasse in Doxygen nachbauen

Es gibt zwar ein paar Tricks, um den Doxygen Parser zu beeinflussen um ihm neue Vokabel beizubringen (für COM existieren solche Zusätze), doch ich hätte gerne eine Lösung, die “Out of the box” funktioniert.

Und die sieht dann so aus:

 /**
  * @interface gate_object_t
  * @brief     Base type of all GATE C objects
  */
 
 /**
  * @fn       char const* get_interface_name()
  * @memberof gate_object_t
  * @brief    Returns on object's interface path name
 * @return   Static string describing the interface.
 *
 * @fn       void release()
 * @memberof gate_object_t
 * @brief    Decrease ref-counter, releases object when count == 0
 *
 * @fn       int retain()
 * @memberof gate_object_t
 * @brief    Increase object's reference counter
 * @return   Returns the current reference counter value
 */


/**
 * @interface  gate_cloneable_t
 * @implements gate_object_t
 * @brief      Base interface for all objects that can be cloned.
 */

/**
 * @fn         gate_result_t clone(gate_cloneable_t** clone)
 * @memberof   gate_cloneable_t
 * @brief      Creates a new object by cloning this object
 * @param[out] ptrclone receives the new cloned object's pointer
 * @return     GATE_RESULT_* result code
 */

Folgendes habe ich gelernt:

• Der Doxygen-Kommentar Block sollte nach dem Macro-Block folgen. Steht er davor, wird GATE_INTERFACE() als Makro oder Funktion erkannt, die dann auch ohne Bedeutung in der Doku steht.
• Wichtig ist auch, dass man zuerst einen Kommentarblock schreibt, der die Klasse deklariert und anschließend einen neuen Kommentarblock für die Funktionen anlegt.
  Wenn man beides in einen Block zusammenfügt kommt keine schöne Doku dabei heraus.
• @memberof nach einem @fn markiert die Funktion als zugehörig zur angegebenen @struct, @class oder @interface.
  (Eigentlich hätte ich ja struct nutzen müssen, aber das eigentlich von der IDL stammende interface benennt dann auch in der Doku die Strukturen als “Interface”).
• Mit @implements werden Vererbungshierarchien definiert, die man dann im generierten Doxygen-HTML auch in einem Graphen durchklicken kann.

Fazit

Naja, ich sehe es jetzt mal als annehmbaren Workaround.
Alle anderen Spielereien mit Doxygen zwischen den Makros haben die generierte HTML Doku nur vernudelt.

Doch mit der Lösung habe ich jetzt endlich etwas funktionierendes, mit dem ich meine Interface Definitionen auch verständlich dokumentieren kann.

Denn eigentlich war dieser offene Punkt einer der Gründe, warum ich seit zwei Jahren die Dokumentation des Projektes immer wieder aufgeschoben habe. Bisher habe ich nur sporadisch freie C-Funktionen mit Doxygen Kommentaren versehen.

Das Schlimme ist … jetzt muss ich meinen hunderten Funktionen auch wirklich mal eine verständliche Bedeutung zuordnen.

Doch das ist auch gut … denn damit erfolgt implizit auch ein Code-Review.