javaDoc Prinzip bloß auf für anderes Sprachen

[empire]

Ich weis nicht obs unbedingt hier her gehört.

Aber ich suche ein Tool zum Dokumentieren von Programmcode.

In unser Firma wird jetzt nach einer gleichen Lösung gesucht wie das JavaDoc.

Und zwar sollen in unserem Code einzelne Tags gesetzt werden und daraus dann eine übersichtliche HTML Dokumentation erstellt werden.

Die Idee war es, vieleicht das JavaDoc anzupassen.

Hab ihr ne Idee vieleicht?

[Olli_Master]

Je nach Sprache gibt es oft schon fertige Lösungen. Und das meiste ist sogar kostenlos

Für C++ benutze ich DoxyGen. Mit der richtigen Konfiguration (und einer kleinen Batch-Datei) erhält man per Doppelklick eine fertige Dokumentation in diversen Formaten (u.a. HTML, CHM, ...). Interessant ist besonders die autom. Generierung von Klassendiagrammen und der Beziehungen zwischen den Klassen.

Doxygen is a documentation system for C++, C, Java, IDL (Corba, Microsoft, and KDE-DCOP flavors) and to some extent PHP and C#.

Alternativen:

Liste von Dokumentations-Tools

Ich hoffe das hilft.

[empire]

Ich hab mir mal das DoxyGen gedownloadet.

Sieht ja aufen ersten Blick ganz net aus.

Aber sag mal wo kann ich den die Tags editieren.

Hab ne Config File angelegt und versucht sie dann dementsprechend zu ändern.

In einer Datei hab ich dann als Tag mal

/**

* Test Test

*/

reingetippt. Sollte er dann nicht diesen Tag dokumentieren? bzw. er machst nicht.

[empire]

Nachtrag:

gibt es ne möglich keit ohne Klassen zu dokumentieren?

Hier mal ein Beipiel Code.

proc Test()

{

    vars variable

    return variable

}

[/PHP]

[Olli_Master]

Es funktioniert auch ohne Klassen (ähnlich wie bei C-Programmen). Das Ergebnis ist dann natürlich weniger übersichtlich.

Beispiel aus der doxygen-dokumentation: http://www.stack.nl/~dimitri/doxygen/docblocks.html#docblocks

Wichtig:

- die zu dokumentierenden Dateien muss in der Konfigurationsdatei angegeben werden (Pfad reicht)

- für die Kennzeichnung der Doku-Kommentare gibt es mehrere Möglichkeiten: statt /*! kannst du auch wie in deinem Beispiel /** verwenden

- die Funktionen, Variablen können wie folgt dokumentiert werden:

*! \file structcmd.h

    \brief A Documented file.


    Details.

*/



/*! \var typedef unsigned int UINT32

    \brief A type definition for a .


    Details.

*/


/*! \var int errno

    \brief Contains the last error code.


    \warning Not thread safe!

*/


/*! \fn int open(const char *pathname,int flags)

    \brief Opens a file descriptor.


    \param pathname The name of the descriptor.

    \param flags Opening flags.

*/


/*! \fn int close(int fd)

    \brief Closes the file descriptor \a fd.

    \param fd The descriptor to close.

*/


/*! \fn size_t write(int fd,const char *buf, size_t count)

    \brief Writes \a count bytes from \a buf to the filedescriptor \a fd.

    \param fd The descriptor to write to.

    \param buf The data buffer to write.

    \param count The number of bytes to write.

*/



typedef unsigned int UINT32;

int errno;

int open(const char *,int);

int close(int);

size_t write(int,const char *, size_t);

und hier die daraus generierte Datei

http://www.stack.nl/~dimitri/doxygen/examples/structcmd/html/structcmd_8h.html

Um eine Doku zu generieren muss du die Konfigurationsdatei entsprechend einrichten. Ggf. ich benutze dafür das Java-Frontend doxywizard

-----

Die genaue Definition, welche Tags existieren kann man in der Doku zu Dokxygen nachlesen:

http://www.stack.nl/~dimitri/doxygen/manual.html

-----

Ich hoffe das hilft dir weiter...

[empire]

jetzt geht es schon gut. Aber sag mal wenn ich eine Variabel dokumentieren will.

Dann geht das ja mit dem Tag \var , aber die Variabeln werden mit vars deklariert.

Kann man selbst Tags neu machen?

Bei der Procedur dokumentation schreibt er mir immer den ganzen Quellcode mit. Ist ja nicht verkehrt aber mal möchte ich auch ohne Quellcode dokumentieren, geht das auch?

thx

[Olli_Master]

Ich benutze nur die eingebauten Tags, die reichen bei C++ vollkommen aus.

Soweit ich weiss kann man die Tags nicht ändern - aber keine Garantie.

Was angezeigt wird (nur Deklaration oder ganzer Quellcode) kann man in der Konfigurationsdatei festlegen. Die Optionen sind auf der doxygen-Website sehr gut beschrieben. Zum Offline-Lesen macht sich die die CHM-Hilfe-Datei ganz gut.

Ich hoffe das hilft dir weiter...

[Olli_Master]

Kleiner Nachtrag:

Zum Thema "Quellltext":

Wenn der Quelltext nicht mit Dokumentiert werden soll, dann sollte folgende Option "INLINE_SOURCES" nicht in der Konfigurationsdatei erscheinen:

http://www.stack.nl/~dimitri/doxygen/config.html#cfg_inline_sources

Zum Thema "Eigene Tags":

Schau dir mal das Doxygen-Kommando ALIASES an:

http://www.stack.nl/~dimitri/doxygen/config.html#cfg_aliases

Ich habs zwar noch nicht selbst benutzt bzw. ausprobiert, so könnte es allerdings funktionieren.