Hallo zusammen.

Ich nutze zur Dokumentation die in Delphi enthaltene XML-Syntax zusammen mit dem Kommentar mit drei Slashes

markieren

Delphi-Quellcode:

/// Das ist Dokumentation

// Das hier nicht

Jetzt wird der Dokumentationskommentar gerade in der XML-Variante sehr umfangreich und man sieht manchmal vor lauter Dokumentation den Code nicht mehr (z.B. wenn man bei einem Enum die Werte jeweils mit einem <summary>-Kommentar versieht.
Ich bin daher auf der Suche nach einer Möglichkeit, per Knopfdruck, Tastenkombination oder Toolbar-Button diese \\\-Kommentare ein- und ausblenden zu können, damit man den eigentlichen Code wieder lesen kann. Kennt jemand eine Lösung oder könnte eine schreiben? Oder wie geht ihr mit sowas um?

Genau das ist der Grund warum ich solche Dokumentationsgeneratoren nicht mag. Aber wozu die Kommentare überhaupt? Benenne deine Enums gescheit und du musst nicht zu jedem einen Kommentar schreiben. Benenne Routinen gescheit und es erübrigt sich ein Kommentar. Benenne die Parameter gescheit und es erübrigt sich ein Kommentar. Den Dokumentengeneartor braucht man dann nur noch um eine Dokumentation zu erstellen, die eine Übersicht des Codes erzeugt, um sich einen Überblick zu verschaffen, wie die Codeteile zusammenarbeiten und wie die Klassenstruktur und -hierarchie aufgebaut ist. UML-Diagramm dazu und man hat alles, was man braucht. Vielleicht noch ein paar selbst getippte einleitende Worte, was die Idee hinter dem ganzen ist und was man sich dabei gedacht hat.

Wir umschließen die Methoden-Kommentare mit

markieren

Delphi-Quellcode:

{$region 'xml-comment: method'}
{$endregion}

und können diese somit alle über den Fold / Unfold Menupunkt des Editor-Kontextmenus aus- bzw. einblenden.

Zitat von Luckie:

Genau das ist der Grund warum ich solche Dokumentationsgeneratoren nicht mag. Aber wozu die Kommentare überhaupt? Benenne deine Enums gescheit und du musst nicht zu jedem einen Kommentar schreiben. Benenne Routinen gescheit und es erübrigt sich ein Kommentar. Benenne die Parameter gescheit und es erübrigt sich ein Kommentar. Den Dokumentengeneartor braucht man dann nur noch um eine Dokumentation zu erstellen, die eine Übersicht des Codes erzeugt, um sich einen Überblick zu verschaffen, wie die Codeteile zusammenarbeiten und wie die Klassenstruktur und -hierarchie aufgebaut ist. UML-Diagramm dazu und man hat alles, was man braucht. Vielleicht noch ein paar selbst getippte einleitende Worte, was die Idee hinter dem ganzen ist und was man sich dabei gedacht hat.

Klar, eine überlegte und stringente Namenskonvention spart viel Dokumentation. Aber gerade in größeren Projekten sind Hinweise zur Verwendung, Abhängigkeiten, Nebeneffekte, etc. auch über Benennungen nicht vollständig abzuhandeln. Es soll auch am Ende keine gedruckte Doku rauskommen (mit UML, etc.), sondern es soll der Delphi-Tooltip entsprechend aufbereitet werden, um schnell die nötigsten Infos zur Hand zu haben (s. Documentation Insight ToolTip Template)

Ich habe schlicht die Farbe auf Fuchsie gestellt. Dadurch heben sich die Kommentare gut ab und man kann sie sowohl gut überlesen als auch gezielt anschauen.

DocumentInsight macht meines Wissens nach auch selber regions um die Dokumentation

Zitat von Stevie:

DocumentInsight macht meines Wissens nach auch selber regions um die Dokumentation

Ja, aber nur teilweise. Bei Enum z.B. sind die Einzelkommentare der Werte ohne Regions

Tooltips werden doch nur benötigt, wenn die Namen nicht selbsterklärend sind. Klar kann man damit rumspielen und wirklich schlimm wird es, wenn ein 'Chef' darauf besteht, alles zu kommentieren.

Klar, wenn man Enumwerte z.B. mit Rot, Grün und Blau benennt und möchte, das der Anwender 'Rot' für Warnmeldungen nimmt, dann gibt es natürlich eine Fraktion, die genau das im Kommentar unterbringen will.

Andere verwenden einfach als Farbnamen "Warnfarbe" und dann war's das.

Überlege doch einfach, wie oft das wirklich nötig ist.

Zitat von Iwo Asnet:

Klar, wenn man Enumwerte z.B. mit Rot, Grün und Blau benennt und möchte, das der Anwender 'Rot' für Warnmeldungen nimmt, dann gibt es natürlich eine Fraktion, die genau das im Kommentar unterbringen will.

Andere verwenden einfach als Farbnamen "Warnfarbe" und dann war's das.

Vor allem nett ist, wenn die Warnfarbe dann mal auf DunkelOcker oder sowas geändert wird. Dann wirds lustig zu verstehen, warum Rot nicht rot ist

Zitat:

Doc-Kommentare ausblenden

http://www.delphipraxis.net/177720-d...c-o-matic.html
http://www.delphipraxis.net/171454-d...ht-nutzen.html


Ich weiß, der Thread ist uralt, aber ich dacht mir es kann nicht schaden die entsprechenden Threads zu verlinken, welche sich auf dieses Thema beziehen, vorallem da die Suchfunktionen das hier relativ weit oben anzeigten.
- gepant ist das Auslagern in eine externe Datei
- zusammenfalten via $REGION ist möglich
- die neueren Delphis können die /// -Kommentare auch ohne Region zusammenfalten