AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren
Thema durchsuchen
Ansicht
Themen-Optionen

Kommentare ausblenden

Ein Thema von Codewalker · begonnen am 15. Feb 2012 · letzter Beitrag vom 3. Mai 2014
Antwort Antwort
Benutzerbild von Codewalker
Codewalker

Registriert seit: 18. Nov 2005
Ort: Ratingen
945 Beiträge
 
Delphi XE2 Professional
 
#1

Kommentare ausblenden

  Alt 15. Feb 2012, 08:52
Hallo zusammen.

Ich nutze zur Dokumentation die in Delphi enthaltene XML-Syntax zusammen mit dem Kommentar mit drei Slashes
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?
  Mit Zitat antworten Zitat
Benutzerbild von Luckie
Luckie

Registriert seit: 29. Mai 2002
37.621 Beiträge
 
Delphi 2006 Professional
 
#2

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 09:21
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.
Michael
Ein Teil meines Codes würde euch verunsichern.
  Mit Zitat antworten Zitat
flipdascript

Registriert seit: 20. Mai 2008
25 Beiträge
 
Delphi 2010 Professional
 
#3

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 09:24
Wir umschließen die Methoden-Kommentare mit
Delphi-Quellcode:
{$region 'xml-comment: method'}
{$endregion}
und können diese somit alle über den Fold / Unfold Menupunkt des Editor-Kontextmenus aus- bzw. einblenden.
  Mit Zitat antworten Zitat
Benutzerbild von Codewalker
Codewalker

Registriert seit: 18. Nov 2005
Ort: Ratingen
945 Beiträge
 
Delphi XE2 Professional
 
#4

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 09:28
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)
  Mit Zitat antworten Zitat
Benutzerbild von jaenicke
jaenicke

Registriert seit: 10. Jun 2003
Ort: Berlin
9.648 Beiträge
 
Delphi 11 Alexandria
 
#5

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 10:23
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.
Sebastian Jänicke
AppCentral
  Mit Zitat antworten Zitat
Benutzerbild von Stevie
Stevie

Registriert seit: 12. Aug 2003
Ort: Soest
4.027 Beiträge
 
Delphi 10.1 Berlin Enterprise
 
#6

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 12:57
DocumentInsight macht meines Wissens nach auch selber regions um die Dokumentation
Stefan
“Simplicity, carried to the extreme, becomes elegance.” Jon Franklin

Delphi Sorcery - DSharp - Spring4D - TestInsight
  Mit Zitat antworten Zitat
Benutzerbild von Codewalker
Codewalker

Registriert seit: 18. Nov 2005
Ort: Ratingen
945 Beiträge
 
Delphi XE2 Professional
 
#7

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 13:00
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
  Mit Zitat antworten Zitat
Iwo Asnet

Registriert seit: 11. Jun 2011
313 Beiträge
 
#8

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 13:05
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.
  Mit Zitat antworten Zitat
schlecki

Registriert seit: 11. Apr 2005
Ort: Darmstadt
148 Beiträge
 
Delphi XE2 Enterprise
 
#9

AW: Kommentare ausblenden

  Alt 15. Feb 2012, 13:30
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
  Mit Zitat antworten Zitat
Benutzerbild von himitsu
himitsu

Registriert seit: 11. Okt 2003
Ort: Elbflorenz
44.184 Beiträge
 
Delphi 12 Athens
 
#10

AW: Kommentare ausblenden

  Alt 3. Mai 2014, 10:48
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
$2B or not $2B
  Mit Zitat antworten Zitat
Antwort Antwort


Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 06:28 Uhr.
Powered by vBulletin® Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz