mikrocontroller.net

Forum: Compiler & IDEs Doxygen - getting started


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
Autor: Walter T. (nicolas)
Datum:
Angehängte Dateien:

Bewertung
0 lesenswert
nicht lesenswert
Hallo zusammen,

ich versuche gerade, mich in Doxygen einzuarbeiten. Die richtig gute 
Anleitung fehlt mir noch, also habe ich es einfach mal probiert, zwei 
zusammengehörige Dateien aus einem Projekt zu Doxumentieren.

Kann ein Mitleser mit etwas Erfahrung in Doxygen mal drübergucken, ob 
ich etwas Wichtiges vergessen oder falsch gemacht habe?

Autor: Vincent H. (vinci)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Der Mischmasch aus Kommentarstilen gefällt mir persönlich nicht (/// und 
/**). Weiters könnte man das @brief bei den Funktionen weglassen was den 
Lesefluss etwas erleichtern würde.

Sonst hät ich persönlich nix auszusetzen.

Autor: öljavjkdshasdf (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Würde die Parameterdokumentation hinter die Parameter setzen.
/** @brief Bruch kuerzen
 * 
 * @return Bruch
 */
frac64_t frac64_reduce(
        frac64_t F   /**< Regulaerer Bruch (Nenner nicht Null!) */
    )
{
    int64_t ggt = gcd_s64(F.z, F.n);
    assert( ggt > 0 );
    F.z/= ggt;
    F.n/= ggt;
    return F;
}

Verhindert falsche Parameternamen, ist weniger schreibarbeit, m.Mn. nach 
übersichtlicher und man sieht direkt welche Parameter noch nicht 
dokumentiert sind.
Das schließende Kommentarzeichen würde ich in eine neue Zeile setzen. 
Hat keinen Nutzen, ist m.Mn. nach schöner.
Ansonsten was Vincent schon gesagt hat würde ich mir einen Start Tag 
aussuchen und den überall durchziehen.

Autor: Walter T. (nicolas)
Datum:
Angehängte Dateien:

Bewertung
0 lesenswert
nicht lesenswert
Vincent H. schrieb:
> Weiters könnte man das @brief bei den Funktionen weglassen was den
> Lesefluss etwas erleichtern würde.

Hmm....wenn ich das @brief weglasse, fehlt die Zusammenfassung (siehe 
Screenshot). Mir wäre es auch lieber, wenn es auch ohne ginge. Gibt es 
da vielleicht einen Parameter?


öljavjkdshasdf schrieb:
> Würde die Parameterdokumentation hinter die Parameter setzen.

Wie markiert man dann [in,out] ? Ich finde leider die entsprechende 
Variante nicht in der Doku.

Edit: Habe es durch Ausprobieren gefunden:
/** @brief Bruch kuerzen
 *
 * @return Bruch */
frac64_t frac64_reduce(
        frac64_t F ///< [in] F Regulaerer Bruch (Nenner nicht Null!)
        )
{
    int64_t ggt = gcd_s64(F.z, F.n);
    assert( ggt > 0 );
    F.z/= ggt;
    F.n/= ggt;
    return F;
}

: Bearbeitet durch User
Autor: Vincent H. (vinci)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Walter T. schrieb:
> Vincent H. schrieb:
>> Weiters könnte man das @brief bei den Funktionen weglassen was den
>> Lesefluss etwas erleichtern würde.
>
> Hmm....wenn ich das @brief weglasse, fehlt die Zusammenfassung (siehe
> Screenshot). Mir wäre es auch lieber, wenn es auch ohne ginge. Gibt es
> da vielleicht einen Parameter?

Tatsächlich, sry fürs unterschlagen:
http://www.doxygen.nl/manual/config.html#cfg_javadoc_autobrief

Autor: Walter T. (nicolas)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
JAVADOC_AUTOBRIEF

Das ist ja famos! Danke! Das macht einiges schöner und ordentlicher. Vor 
allem in Structs.

: Bearbeitet durch User

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.