Doxygen - getting started

[Walter T. (nicolas)]

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?

[Vincent H. (vinci)]

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.

[öljavjkdshasdf (Gast)]

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.

[Walter T. (nicolas)]

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;
}

[Vincent H. (vinci)]

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

[Walter T. (nicolas)]

JAVADOC_AUTOBRIEF

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