Wie integriert man Beispiele in Doxygen?

Question

Ich habe alle meine Klassen dokumentiert und möchte nun ein Beispiel für die Verwendung dieser Klassen integrieren. Wie kann ich das tun?

Answer 1

Sie können den Quellcode der Beispiele in einem speziellen Pfad ablegen, der in der Doxygen-Konfiguration unter EXAMPLE_PATH und fügen Sie dann Beispiele mit der Option @example Tag.

Doxygen generiert dann eine zusätzliche Seite, die den Quelltext des Beispiels enthält. Außerdem wird ein Link von der Klassendokumentation, die das Beispiel-Tag enthält, auf diese Seite gesetzt.

Wenn Sie kleine Codeschnipsel verwenden möchten, können Sie diese alternativ mit @code ... @endcode

Die Dokumentation dazu finden Sie hier: Doxygen-Dokumentation ?

Answer 2

Eine andere Möglichkeit ist die Verwendung der \snippet Befehl.

• Schreiben Sie in Ihre Header-Datei etwas wie:

\section ex1 Example
\snippet path_to_test_class/TestClass.cpp TestClass example
\section ex2 Expected output
\snippet path_to_test_class/TestClass.cpp TestClass expected output

• In der Datei TestClass.cpp, haben etwas wie:

 //! [OptimizeSpeedOnTrackTest example]
 Class c;
 const double res = c.do_something();
 //! [OptimizeSpeedOnTrackTest example]
 //! [OptimizeSpeedOnTrackTest expected output]
 ASSERT_DOUBLE_EQ(5,res);
 //! [OptimizeSpeedOnTrackTest expected output]

path_to_test_class muss sich in Ihrem EXAMPLE_PATH befinden.

Daraus ergeben sich die folgenden Möglichkeiten:

• Ihre Beispiele dienen nicht nur der Dokumentation, sondern auch der Testabdeckung.
• Ihr Test-Runner (und Ihr Compiler) gibt Ihnen die Sicherheit, dass Ihre Beispiele tatsächlich kompiliert und ausgeführt werden
• Es passt ziemlich gut in einen TDD-Workflow

Answer 3

Ich hatte einige Fehler bei der Verwendung von @example, um die Beispieldatei in die Dokumentation aufzunehmen. Dies ist die Umgehung, die ich verwendet habe.

Ort examplefile.cs in einem Ordner/Projekt speziell für Beispielcode. Legen Sie diesen Ordner in den Doxygen EXCLUDE Liste (Experten->Eingabe->EXCLUDEim Doxygen GUI-Frontend) und in der EXAMPLE_PATH (Expert->Input->EXAMPLE_PATH im Doxygen GUI-Frontend)

Platzieren Sie diesen Codeblock irgendwo in einer dokumentierten Datei (ich habe ihn in die Datei eingefügt, für die das Beispiel gilt).

/** @example examplefile.cs
 * A description of the example file, causes the example file to show up in 
 * Examples */

Dies führt dazu, dass die Datei im Doxygen-Menü unter Beispiele angezeigt wird, aber nicht als Klasse/Datei in Ihrem Projekt erscheint.

Dokumentieren Sie dann Ihre Klasse/Funktion:

/** @brief MyClass does something
 * @details I have something more long winded to say about it.  See example 
 * in examplefile.cs: @include examplefile.cs */

Dadurch wird die Beispieldatei in der Dokumentation von MyClass vollständig ausgedruckt.

Answer 4

1. einen Weg zu doxyfile hinzufügen EXAMPLE_PATH = dir_example \

2. können alle Beispiele in derselben Datei wie example_list.h einbinden und INPUT = example_list.h \

(Sprache - Russisch) http://www.scale-tech.ru/SimBookmaker/doc/html/examples__list_8h_source.html et http://www.scale-tech.ru/SimBookmaker/doc/html/examples.html