Wie füge ich Markup für Beispielprogrammseiten in Doxygen hinzu?

Question

Ich habe eine Reihe von Doxygen-generierten Bibliotheksdokumentation, komplett mit Beispielprogrammen. Sie erscheinen gut unter der Registerkarte "Beispiele" in der resultierenden Dokumentation. Ich möchte diesen Seiten eine Art Doxygen-Markup hinzufügen, kann aber nicht herausfinden, wie es geht. Alle Markup-Kommentare werden entfernt und erscheinen nirgendwo in der Doxygen-Ausgabe. Ich hoffe, einige beschreibende Absätze und vielleicht eine Reihe von Programmausgaben, die der Benutzer betrachten kann, einzubeziehen. Meine Problemumgehung ist vorläufig, all das Recht im Quellcode als Nicht-Doxygen-Kommentare einzubeziehen. Dieser Ansatz funktioniert, aber ich habe nicht gehofft.

/** 
* \brief ATTEMPTED DESCRIPTION 
* 
* I would like to include some kind of markup on the example page for 
* this program. I link to it just fine from one of my library routines, 
* the the Doxygen-generated example page just shows all of this verbatim. 
* 
* Is there any way to provide some kind of section where I can discuss 
* the example program itself? And potentially provide sample output 
* and the like? (I realize that doesn't make sense for "Hello World", 
* but you get the idea.) 
*/ 

#include <iostream> 

int main (int argc, char *argv[]) 
{ 
    std::cout << "Hello World" << std::endl ; 

    return 0 ; 
} 

Answer 1

Nach dieser Frage im Laufe des letzten Monats zu erkunden, habe ich festgestellt, dass Sie nicht effektiv Ausgabe des doxygen ändern können mit Markup innerhalb der Beispielprogrammdatei.

Die Lösung ist eine eigene Seite in der Dokumentation zu bauen, sind den Beispielcode mit der \include Richtlinie und dann bieten Links zu dieser neuen Beispiel Seite manuell. Erstellen Sie für das obige Beispiel eine Datei mit dem folgenden Format, und verwenden Sie die \include-Anweisung, um den tatsächlichen Code aus Ihrem Beispielprogramm hinzuzufügen. Es ist dann einfach, eine Erzählung und einen Abschnitt für Programmausgabe hinzuzufügen. In diesem Beispiel

, erstellen Sie die Datei example-hello-world.dox mit folgenden Struktur:

/*! \page ex-page Example Program Page 
* 
* \brief Example code for the "hello world" program. 
* 
* \section ex-sec-description Program Details 
* 
* In order to display the string "Hello World" to the standard output 
* stream, the user should use the `std::cout` stream provided by C++. 
* 
* \include example_hello_world.cpp 
* 
* \section ex-sec-output Program Output 
* 
* The program above will generate the following output when executed. 
* 
*   Hello World 
*/