Beste Tipps zum Dokumentieren von Code mit Doxygen? [closed]

Question 1

Mein Team beginnt mit der Dokumentation unseres C-Codes mit Doxygen und achtet dabei besonders auf unsere öffentlichen API-Header. Es scheint eine Menge Flexibilität und verschiedene Spezialbefehle in Doxygen zu geben, was großartig ist, aber ohne Versuch und Irrtum ist nicht klar, was gut und was schlecht ist.

Was sind Ihre Lieblingsmethoden, um Ihren Code zu markieren, was sind Ihre MUSS und NICHT?
Bitte geben Sie Ihre Top-Tipps an, einen pro Antwort, um die Abstimmung zu erleichtern.

Ich möchte unseren gesamten Ansatz für die API-Dokumentation definieren, einschließlich der Bereitstellung einer Vorlage, um dem Rest des Teams den Einstieg zu erleichtern. Bisher habe ich so etwas:

/**
 * @file   example_action.h
 * @Author Me ([email protected])
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did something.
 *
 * Example Usage:
 * @code
 *    example_nada(3); // Do nothing 3 times.
 * @endcode
 */
boolean example(int repeat);

Question 2

Sie brauchen und sollten den Namen der Datei nicht in die schreiben @file Direktive liest doxygen den Namen der Datei automatisch. Das Problem beim Schreiben des Dateinamens besteht darin, dass Sie beim Umbenennen der Datei die ändern müssen @file auch Direktive.

Bereitstellen @author Und @date Informationen sind die meiste Zeit auch nutzlos, da das Versionskontrollsystem es viel besser macht als jemand, der die Dateien manuell bearbeitet.

Du musst auch nicht schreiben @brief wenn Sie die folgende Doxygen-Syntax verwenden und JAVADOC_AUTOBRIEF in der Konfiguration von Doxygen aktivieren:

/*! Short Description on the first line

    Detailed description...
    ...
*/
void foo(void) {}

Der @name Direktive für Funktionen ist auch meistens zu 100% redundant und völlig nutzlos. Es bringt nur Fehler, wenn jemand den Namen der Funktion ändert und nicht das Doxygen @name.

Question 3

Schreib ein beschreibende Homepage mit @mainpage (in einer separaten Header-Datei nur für diesen Zweck). Erwägen Sie, wie in meinem Beispiel gezeigt, es zu einem Leitfaden für Ihre Hauptklassen/Funktionen und Module zu machen.

Eine weitere Probe

Während ich den oben verlinkten Haupt-Oofile-Doxygen-Inhalt wieder online stellte, ist hier ein Beispiel aus einer aktuellen Kundenarbeit im Markdown-Format. Mit Markdown können Sie auf eine Hauptseite in Markdown (in den Doxygen-Einstellungen) verweisen, was für das Typische großartig ist readme.md Datei, die in Open-Source-Projekten enthalten ist.

Lingopal
========
Developer Documentation started when Andy Dent took over support in May 2014. 

There are a number of pages in Markdown format which explain key aspects:

- @ref doc/LingopalBuilding.md
- @ref doc/LingopalSigning.md
- @ref doc/LingopalDatabases.md
- @ref doc/LingopalExternals.md

See the <a href="https://stackoverflow.com/questions/51667/pages.html">Related Pages list for more.</a>

-------------

_Note_

These pages, whilst readable by themselves, are designed to be run through the [Doxygen](http://www.doxygen.com) code documentation engine which builds an entire local cross-referenced set of docs. It uses a minor [extension of Markdown formatting.](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)

The settings to generate the documentation are `Lingopal.doxy` and `LingopalDocOnly.doxy`. The latter is used for quick re-generation of just these additional pages.

Question 4

Verwenden Gruppen um Ihren Code in Module zu organisieren.

Denken Sie daran, dass Sie fast alles in mehrere Gruppen packen können, damit sie wie die Tags in Stack Overflow für semantisches Tagging verwendet werden können. Beispielsweise können Sie Dinge als spezifisch für eine bestimmte Plattform kennzeichnen.

Sie können auch Gruppen verwenden, um a abzugleichen Ordnerhierarchie innerhalb einer IDEwie in meinem RB2Doxy-Beispiel gezeigt Ausgang.

Gruppen funktionieren gut, wenn sie verschachtelt sind – ich habe ein großes Beispiel dafür OOFILE-Quelle.

Question 5

Einige Befehle, die ich in meinem Code verwende:

\todo { paragraph describing what is to be done } Nützlich, um Todos im Auge zu behalten, wird in der endgültigen Dokumentation eine Seite erstellt, die Ihre Todo-Liste enthält.
\c <word> Zeigt das Argument mit einer Schreibmaschinenschrift an. Verwenden Sie dies, um auf ein Codewort zu verweisen. Ich würde es in Ihrem Beispiel vor “TRUE” und “FALSE” verwenden.
\a , \warning , \see : sehen http://www.stack.nl/~dimitri/doxygen/commands.html#cmdc zur Beschreibung

Question 6

Eine gute „Best Practice“ (obwohl nicht immer erreichbar) besteht darin, kurze, funktionierende Beispiele für jede API bereitzustellen und sie mit \includelineno (oder \include für keine Zeilennummern) in die Hilfe zu ziehen. Dies können Einheitentests sein, wenn sie so geschrieben sind, dass Benutzer sie verstehen können (dh nicht in einen größeren Testrahmen eingebunden sind). Als netter Nebeneffekt machen Änderungen an der API die Samples kaputt, sodass sie auf dem neuesten Stand gehalten werden müssen.

Sie können eine API in Worten beschreiben, aber es gibt nichts Besseres, als den tatsächlichen Code zu sehen, um zu verstehen, wie man ihn verwendet.

Question 7

Da ich Code auf Bildschirmen mit höherer Auflösung bearbeite, bin ich von der Verwendung des umgekehrten Schrägstrichs zum @-Präfix für Doxygen-Befehle übergegangen. Nicht so laut Backslash hat sich jetzt gefunden zu verdammt schwer, um die Doxygen-Befehle zu verstehen.

Question 8

Wenn Sie sicher sind, dass Ihr Team einer so schwergewichtigen Vorlage folgen wird, verwenden Sie sie wie gezeigt.

Ansonsten sieht es aus wie JavaDoc. Eines der schönen Dinge an Doxygen ist, wie gut es seine Arbeit macht ohne so starkes Markup verwenden zu müssen. Sie müssen @name nicht verwenden und mit der JAVADOC_AUTOBRIEF-Einstellung können Sie @brief überspringen – stellen Sie einfach sicher, dass die erste Zeile des Kommentars eine angemessene kurze Beschreibung ist.

Ich bevorzuge aussagekräftige Namen, anstatt die Dokumentation zu erzwingen, und ermutige die Leute, Kommentare nur dann hinzuzufügen, wenn sie einen erheblichen Mehrwert bieten. So werden die wertvollen Kommentare nicht von all dem übertönt Lärm.