Dokumentations-Standard

[pyromania]

Hallo,

ich würde gerne wissen, ob es irgendeinen 'Dokumentations-Standard' gibt, also das irgendwo festgelegt ist, wie was dokumentiert wird.

Bisher hab ich nämlich nur verschiedene Ansätze gesehen, darunter:

Doxygen:

/// \brief  Exemplarische Funktion
///
///         Diese Funktion gibt den übergebenen Parameter
///         Auf der Konsole aus.
///
/// \param      parameter   Auszugebender Parameter
/// \return                 Status-Code

Dann das Microsoft-Eigene Zeugs:

/// <summary>
/// Exemplarische Funktion
///
/// Diese Funktion gibt den übergebenen Parameter auf der Konsole aus.
///
/// <param name="parameter">Auszugebender Parameter</param>
/// <returns>Status-Code</returns>
/// </summary>

Dann gibt es auch noch ein anderes Format, allerdings hab ich nicht rausgefunden, wie es heißt:

/**
* Exemplarische Funktion
* 
* Diese Funktion gibt den übergebenen Parameter auf der Konsole aus.
*
* @return Status-Code
* @param parameter Auszugebender Parameter
*/

Was ist denn nun die 'richtige' Methode, welche hat Vorteile und welche Nachteile und welche wurde 'standardisiert'?

Das sind ziemlich viele Fragen, aber ich hoffe ihr könnt sie beantworten

Danke schonmal,
Gruß pyro

[lolz_ausgeloggt]

Das unterste ist auch Doxygen, Doxygen versteht sehr viele "Formate".

[cubeman]

Das letzte ähnelt dem Javadoc Standard, den ich bevorzuge (wozu - wie im Microsoft Standard - öffnende und schließende Tags - eine Schikane!).

Vom C++ Standard gibt es aber keine Vorgaben soweit ich weiß...

[Tyrdal]

Wird direkt als xml verwurstet, daher die Tags. Aber der JavaDoc Stil ist mir auch lieber.

[Ben04]

MS-Style ist Scheiße weil zu der eh schon vielen Tipparbeit noch mehr hinzufügt ohne, dass es irgendetwas an Mehrwert bringt. Doxygen schafft es auch aus seinem Format XML zu erzeugen und dann ist nicht mal mehr extra Flexibilität eine Argument für MS.

Das letzte ist javadoc wird aber auch problemlos von Doxygen verstanden.