Wie in der Lage sein, um Kommentare in doxygen aus dem Innern einer Funktion zu extrahieren?

StackOverflow https://stackoverflow.com/questions/758045

Frage

Ich bin daran interessiert zu wissen, ob es möglich ist, einige Kommentare in einer Funktion zu haben (c, c ++, Java) in einer Weise, dass doxygen sie in der generierten HTML-Datei setzen könnte.

Beispiel: 

function(...)
{
do_1();
/**
 * Call do_2 function for doing specific stuff.
 */ 
do_2();
}
War es hilfreich?

Lösung

Nein, doxygen nicht Kommentare Blöcke innerhalb Funktion Körper unterstützen. Aus dem Handbuch:

  

Doxygen können Sie Ihre Dokumentation Blöcke stellen praktisch überall (die Ausnahme innerhalb des Körpers einer Funktion oder in einem normalen C-Stil Kommentarblock).

Sektion: Doxygen den Code dokumentieren

Andere Tipps

Ich weiß nicht, für C, aber ich es in Objective-C jeden Tag tun, wo ich Anmerkungen wie: 

/// This method perform the following operations:
- (void) myMethodWith: (id) anObjectArgument
{
    /// - do op1
    [self op1];

    /// - do op2
    op2(anObjectArgument);
}

was macht wie:

  

Diese Methode führt die folgenden   Operationen:

     
      

  • do op1

    •   

  • do op2

    •   

Edit:. folgender Kommentar von Dana der Sane, über mein Verständnis von Doxygen Dokumentation und warum es nicht im Widerspruch mit meiner Erfahrung

Soweit ich verstehen und interpretieren, die Doxygen Dokumentation, ist dies nicht im Widerspruch zu der Zitat von Aaron Saarela zur Verfügung gestellt. Zu Beginn der Verbindung er sieht, gibt es einen Abschnitt über in Körper Dokumentation:

  

Für jeden Code Artikel gibt es zwei (oder   in einigen Fällen drei) Arten von   Beschreibungen, die zusammen das bilden,   Dokumentation: eine kurze Beschreibung und   detaillierte Beschreibung, beide sind   Optional. Für Methoden und Funktionen   gibt es auch eine dritte Art von   Beschreibung, die so genannte „in Körper“   Beschreibung, die aus der aus   Verkettung aller Kommentarblöcke   innerhalb des Körpers des Verfahrens gefunden oder   Funktion.

Das bedeutet, dass es OK Doxygen Dokumentation in einer Funktion oder Methode Körpern zu setzen. Dies ist, was ich auf meiner Antwort beschrieben.

Meiner Meinung nach ist der Absatz von Aaron zitierte bezieht sich auf Unterlagen, die in der Regel vor Funktions- oder Methodendeklaration oder implementaiton gestellt wird. Dies ist die eine, die Parameter, Rückgabewerte und so weiter beschrieben. Die Überschrift Dokumentation kann nicht im Innern des Körpers von einer Funktion oder Methode gesetzt werden.

Aber eine ausführliche Dokumentation jeden Schritt eines Algorithmus innerhalb eines Körpers über perfekt durch Doxygen behandelt.

Kommentare in den Code sollen eine bestimmte Implementierung Schnipsel erklären, für andere Programmierer zu verstehen, nicht ein Merkmal der Funktion für die Benutzer über zu lesen.

Wenn es für Benutzer dokumentiert werden muss, sollte es gemacht werden ouside der Funktionsblock, auf einen Kommentar Definition der Schnittstelle (Unterschrift sowie Vorbedingungen Nachbedingungen, Anwendungsbeispiele oder was auch immer Sie für notwendig erachten ).

Vielleicht stattdessen könnten Sie den Code der Funktion als ein Beispiel setzen. http://www.doxygen.nl/manual/commands.html#cmdexample

Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top