XML-Dokumentation im Implementation-Abschnitt wird nicht erzeugt

[ToFaceTeKilla]

Hallo zusammen,

ich würde gerne die XML-Codedokumentationsfunktion nutzen. Den entsprechenden Schalter in den Projektoptionen (Compilieren -> XML-Dokumentation erzeugen) habe ich auch auf true gesetzt. Das Problem ist, dass die Kommentare (z.B. <summary>...</summary>) nur ausgewertet werden, wenn sie im Interface-Teil stehen. Dann werden sie mir auch in der Symbolbeschreibung angezeigt.
Ich finde das allerdings unschön, den Interface-Abschnitt so mit Kommentaren aufzublähen. Und laut dem Emb-Wiki sollte das eigentlich auch im Implementation-Abschnitt funktionieren.

Ist das nur bei mir so oder ist das ein genereller Bug? Hätte evtl. jemand eine Idee, wie man das beheben kann?


Vielen Dank für die Aufmerksamkeit

[ToFaceTeKilla]

*Schieb*

Wäre jemand so freundlich, es mal auszuprobieren, ob das bei ihm auch so (nicht) funktioniert?

Danke

[sx2008]

Möchtest du den Code für Dich selbst oder für andere dir möglicherweise noch unbekannte Programmierer bereitstellen?

Wenn der Sourcecode als Open Source veröffentlicht werden soll, oder wenn er an andere Kunden verkauft werden soll, dann ist die XML-Dokumentation im Prinzip eine gute Sache.
Wenn der Sourcecode aber nur von Dir und vielleicht noch deinen Kollegen benutzt/bearbeitet wird, dann ist die XML-Doku eher sogar störend.

Fängt man mit der XML-Doku an, dann ist man praktisch gezwungen es komplett durchzuziehen.
Das Verhältnis zwischen Sourcecode und Kommentaren erreicht dann 50:50.
Das ist Erstens eine grosse Zeitverschwendung wenn man die Doku nicht wirklich braucht und Zweitens
verhindert es Fortschritt und Umstrukturierungen im Code.

Wer würde Funktions-, Klassen- und Parameternamen einfach so umbenennen, wenn er ständig die XML-Kommentare nacharbeiten muss?
Wer würde sich trauen eine ganze Unit wegzuwerfen (weil z.B. der Ansatz schlecht war) und alles nochmal neu programmieren wenn er die ganzen schönen Kommentare verlieren wird?
Kommentare altern übrigens schneller als der Sourcecode; bzw. der Sourcecode verändert sich und die Kommentare werden vergessen.
Was ist schlimmer: kein Kommentar oder überall falsche, veraltete Kommentare?

XML-Kommentare haben also auch einige Nachteile.
Nur wenn man den Sourcecode an eine breite Leserschaft verbreitet, machen XML-Kommentare einen Sinn (oder für eine Diplomarbeit) ansonsten lieber Finger weg von der Zeitverschwendung.

[ToFaceTeKilla]

Ja, da hast du recht. Es ist natürlich etwas overkill für ein kleines Team (proprietär, auf absehbare Zeit keine Weitergabe an Dritte).
Aber es wurde nun mal so beschlossen, dass das gemacht werden soll, also bleibt mir ja nichts anderes übrig.
Es wäre jetzt halt schön, wenn ich sowieso die Kommentare schreibe, wenn die gleich noch diesen zusätzlichen Zweck erfüllen würden.

Wärest du so gut und probierst das mal eben aus? Gehört ja nichts weiter dazu

Delphi-Quellcode:

///<summary>Test</summary>

davor und die o.g. Option in den Projektoptionen auf true setzen.

Edit:
Achso, sehe gerade, du hast D2007. Wenn das da schon geht, nützt mir das ja nix. Müsste mal jemand mit XE2 probieren.

[sx2008]

Zitat:

Zitat von ToFaceTeKilla (Beitrag 1199111)

Aber es wurde nun mal so beschlossen, dass das gemacht werden soll, also bleibt mir ja nichts anderes übrig.

Ja, das kenne ich nur zu gut. :(
Aber ein gutes Team kann schlechte Entscheidungen auch wieder korrigieren (es sei denn der Chef stellt sich quer).
Argumentationshilfe hast du ja jetzt.

Es gibt noch einen Grund, weshalb XML-Kommentare im Implementation-Abschnitt ignoriert werden.
Die XML-Kommentare beschreiben z.B. das Interface einer Klassenbibliothek mit grafischen Effekten.
Zielgruppe sind Programmierer, die sich schnell einen Überblick verschaffen wollen.
WIE etwas implementiert interessiert hier nicht und gehört nicht in diese Doku.

Das heisst also, selbst wenn der Interface-Abschnitt mit XML-Doku gepflastert ist, bleibt alles nach Implementation davon frei und man benützt ganz normale Kommentare in diesem Bereich.

Zusätzlich sollten grössere Projekte aber noch ein eigenes Text- oder Word-Dokument namens "Programmer's Guide" haben, in dem man technische Aspekte und Entscheidungen festhält.
Dieses Dokument wäre der ideale Einstiegspunkt für neue Programmierer die ins Team aufgenommen werden.
Der Programmer's Guide wird von jedem Teammitglied gepflegt und wie Sourcecode in die Versionsverwaltung eingefügt.