Welche Techniken zur Source Code Dokumentation nutzt ihr ?

[HeinzJ]

Ich möchte eine Entscheidung darüber treffen, welche Technik der Sourcecodedokumentation ich zukünftigt verwenden will.
Welche Techniken oder Tools nutzt ihr ?

[RWarnecke]

Ich dokumentiere meinen Sourcecode im Sourcecode. Das soll heissen, dass ich aussagekräftige Namen für alles nehme (Komponenten, Variablen, Procedure und Funktionen). Dazu kommt noch eine kurze Beschreibung, was die Funktion oder Procedure macht oben drüber. Dann noch eventuell ein paar Kommentare in den Sourcecode selber, wenn er etwas unübersichtlich wird (z.B. bei verschachtelten IF-Abfragen).

[Bernhard Geyer]

Bisher Inlinedoku auf JavaDoc-Basis. Kann z.B. mit Doc-O-Matic in HLP/HTML/CHM/... gewandelt werden.

[HeinzJ]

JavaDoc ist bisher auch mei Favorit. Neben @JavaDoc und ///Inline Dokumentation scheint es da noch XMLDoc zu geben. Auch bei Jedi soll noch irgendeine Syntax vrumschwirren. Mir scheint, dass JavaDoc, Inline und XMLDoch die Favoriten bei der Source Code Dokumentation sind.

[HeinzJ]

Habe mal die Express Version von Doc-O-Matic getestet.
Scheint zu funktioniern und sieht interessant aus.
Die generierte HTML Doku finde ich allerding recht unübersichtlich.

[mjustin]

Zitat von HeinzJ:

Ich möchte eine Entscheidung darüber treffen, welche Technik der Sourcecodedokumentation ich zukünftigt verwenden will.
Welche Techniken oder Tools nutzt ihr ?

"doxygen"

Damit kann man Compiiled HTML (CHM) und HTML Hilfe, Tex, RTF u.a. erstellen. Es unterstützt viele Sprachen, leider nicht aber standardmäßig Pascal.
Aber ein Delphi - Entwickler hat freundlicherweise pas2dox gechrieben, das als Importfilter für doxygen arbeitet.

Doxygen habe ich für Open Source Projekte verwendet, zum Beispiel:

http://btvisualftp.sourceforge.net/

Neuere Versionen erzeugen auch einblendbare Vererbungsdiagramme

[HeinzJ]

mjustin schrieb:

Zitat:

Doxygen habe ich für Open Source Projekte verwendet, zum Beispiel:
http://btvisualftp.sourceforge.net/

Das sieht ja schon mal ganz gut aus.

Die Dokumentation für pas2dox ist aber so mal erst recht dürftig.
Kannst du eventuell mal eine doxygen Konfigurationsdatei hier posten, mit der man mal ein wenig rumspielen kann ?

Grüße, Heinz

[mjustin]

Zitat von HeinzJ:

mjustin schrieb:

Zitat:

Doxygen habe ich für Open Source Projekte verwendet, zum Beispiel:
http://btvisualftp.sourceforge.net/

Das sieht ja schon mal ganz gut aus.

Die Dokumentation für pas2dox ist aber so mal erst recht dürftig.
Kannst du eventuell mal eine doxygen Konfigurationsdatei hier posten, mit der man mal ein wenig rumspielen kann ?

Grüße, Heinz

Ok, ist im Anhang - hier das wesentliche

# Doxyfile 1.4.4

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------

PROJECT_NAME = BTVisualFTP

OUTPUT_DIRECTORY = target/btvisualftp/docs

...

#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------

INPUT = target/btvisualftp/source

FILE_PATTERNS = *.pas

# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
# by executing (via popen()) the command <filter> <input-file>, where <filter>
# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
# input file. Doxygen will then use the output that the filter program writes
# to standard output. If FILTER_PATTERNS is specified, this tag will be
# ignored.

INPUT_FILTER = make\pas2dox

...

CHM_FILE = BTVisualFTP.chm

HHC_LOCATION = "C:/Programme/HTML Help Workshop/hhc.exe"

...


Oder bei Sourceforge unter

http://btvisualftp.svn.sourceforge.n...tp/trunk/make/

(doxygen.cfg)

[HeinzJ]

Danke für die Hilfe mjustin

Ich habe nun das Problem, dass nicht alle Klassen in der Klassenhierachie auftauchen, sondern nur in der Dateiliste. Ich nutze chm/html als Ausgabeformat in Doxygen. Ist dies ein Fehler des pas2dox / doxygen Duos ?

[mjustin]

Zitat von HeinzJ:

Danke für die Hilfe mjustin

Ich habe nun das Problem, dass nicht alle Klassen in der Klassenhierachie auftauchen, sondern nur in der Dateiliste. Ich nutze chm/html als Ausgabeformat in Doxygen. Ist dies ein Fehler des pas2dox / doxygen Duos ?

Nein, das funktioniert bei mir bestens. Man kann in der doxygen.cfg als Hilfe eine Datei angeben, in die Warnungen ausgegeben werden:


# The WARN_LOGFILE tag can be used to specify a file to which warning
# and error messages should be written. If left blank the output is written
# to stderr.

WARN_LOGFILE = warnings.log


Darin steht eventuell etwas mehr über die Probleme mit bestimmten Dokumenten.

Auch die stdout-Ausgabe von doxygen sollte man beobachten, vielleicht steht dort auch ein Hinweis.


Als funktionierendes Beispiel könnte auch

http://btvisualftp.svn.sourceforge.n...sualftp/trunk/

eventuell helfen.