Verwendung von fpdoc

[braunbär]

Angeregt durch das neue Lazarus Handbuch wollte ich mir einmal das Dokumentationstool fpdoc anschauen.

fpdoc zeigt mir ein leeres Formular an, und es erkennt, wenn ich mit dem Cursor auf eine bekannte Datei gehe. Es zeigt dann zwar den entsprechenden xml Dateinamen an, aber sonst zeigt es gar nichts an, ich habe schon alles mögliche versucht und komme nicht weiter.
Doe forms.xml ist vorhanden und wird mit XML öffnen in einem neuen Tab des Lazarus Editors geöffnet. Das ist aber auch schon alles, fpdoc tut sonst nichts...


Die anderen Tabs bleiben genauso leer.

[Ich934]

Naja hast du den schon einen Eintrag für deine Funktion etc erstellt? Es zeigt das an was du angelegt hast. Nichts angelegt führt auch zu einer leeren Anzeige.

[braunbär]

Ich wollte mir die Dokumentation von vorhandenen LCL Klassen und Methoden anschauen, um zu sehen, was man typischerweise in die Felder hineinschreibt (mit "Link" kann ich zum Beispiel nichts anfangen).
Im angehängten Bild sihst du in der Titelleiste forms.xml angezeigt, der Cursor steht auf TForms. TForms kennt er offensichtlich, sonst würde nicht die richtige XML Datei in der Titelzeile angezeigt werden. Ein Dokumentationsfile dazu ist auch tatsächlich vorhanden, wenn ich auf XML öffnen klicke, dann wird die entsprechende XML Datei im Editor-Tab geöffnet. ABer im fpdoc Fenster zeigt er dazu nichts an, das bleibt leer.

edit: Ich habe jetzt noch etwas herumgespielt, und es ist mir gelungen, zu einer eigenen Funktion einen Eintrag abzuspeichern. Aber dabei hat fpdoc zwei mal die IDE komplett zum Absturz gebracht (Ausnahmeverletzung, danach reagierte die IDE nicht mehr und musste via Task Manager beendet werden.) Zu vorhandenen LCL Bezeichnern zeigt das Fenster nach wie vor keine Daten an.

[wp_xyz]

Klicke auch mal auf die anderen Laschen ("Vererbt", "Beschreibung"), die Einträge sind nicht immer konsistent ausgefüllt. Und wenn du eine ältere Lazarus-Version verwendest, können viele Einträge noch sehr leer sein. Erst in letzter Zeit gibt es viele Updates an den Hilfe-Dateien durch User "dsiders".

[braunbär]

Tatsächlich scheint eine Menge leer zu sein. Ein paar Sachen habe ich angezeigt bekommen.
Trotzdem blicke ich nicht durch.
Ich habe die XML Files für den FPC heruntergeladen und in das Verzeichnis \Lazarus\fpc\fpcdocs gespeichert. Dann habe ich unter IDE Einstellungen - FPDOC Einstellungen das Verzeichnis ($Lazdir)\fpc\fpcdocs hinzugefügt.
In dem Verzeichnis befindet sich ein File dateutils.xml. Wenn ich den Cursor auf das Wort dateutils in der uses clause meiner Unit lege, sollte doch im FPDoc Editor der entsprechende Eintrag angezeigt werden. Das ist aber nicht der Fall. Das Wort dateutils scheint nicht einmal in der Titelleiste des Editors auf.


In der Datei c:\lazarus\fpc\fpcdocs\dateutils.xml befindet sich der Eintrag

Code: Alles auswählen

<element name="IsToday">
<short>Check whether a given date is today.</short>
<descr>
<var>IsToday</var> returns <var>True</var> if <var>AValue</var> is today's
date, and <var>False</var> otherwise.
</descr>
<seealso>
<link id="Today"/>
<link id="Yesterday"/>
<link id="Tomorrow"/>
<link id="IsSameDay"/>
</seealso>
<example file="datutex/ex20"/>
</element>

Wenn ich den Cursor im Quelltext auf das wort istoday platziere, dann erscheint im fpdoc Editor in der Titelleiste immerhin der Text "FPDoc-Editor - IsToday - <KEINE>", aber davon abgesehen sind alle Reiter leer.

Dazu schein fpdoc für ein anderes Problem verantwortlich zu sein, das zuletzt unregelmäßig aufgetreten ist, seit ich mit fpdoc herumprobiere - ich bin nicht 100% sicher, aber ich glaube, es tritt nur auf, wenn der fpdoc Editor angezeigt wird: Ich kann ohne erkennbaren Grund manche Teile des Quelltexts nicht mehr mit der Maus markieren. Es werden nur ein paar Buchstaben markiert, manchmal nur einer, manchmal gar keiner, und wenn ich mit der Maus (mit gedrückter Maustaste) weiterfahre, bleibt der weitere Text, über den ich die Maus bewege, unmarkiert. Manche andere Bereiche des Quelltexts lassen sich dann aber auch normal markieren. Eine Regel, wann das passiert und welche Teile des Quelltexts sich nicht mehr markieren lassen, ist für mich nicht erkennbar.

[m.fuchs]

Falls es dir nicht um fpdoc im Speziellen sondern um Dokumentationsmöglichkeiten deines Quellcodes im Allgemeinen geht, kann ich PasDoc (https://github.com/pasdoc/pasdoc/wiki) empfehlen. Ist aus meiner Sicht deutlich leichter zu benutzen und die Dokumentation wird direkt als Kommentar im Quellcode geschrieben.

[wp_xyz]

[...] in das Verzeichnis \Lazarus\fpc\fpcdocs gespeichert. Dann habe ich unter IDE Einstellungen - FPDOC Einstellungen das Verzeichnis ($Lazdir)\fpc\fpcdocs hinzugefügt.

Ist schon ne Zeit her, dass ich etwas mit fpdoc gemacht habe...

Standardmäßig sind die xml-Hilfe-Dateien im Verzeichnis (lazarus)\docs\xml und den entsprechenden Unterverzeichnissen. Und das wird m.E. auch standardmäßig immer mit installiert, und ist auch im svn-Checkout enthalten. Da muss man keine eigenen Verzeichnisse setzen...

Ich mache folgendes:

• FPDoc-Editor öffnen und auf die Seite ziehen, so dass er nichts wichtiges überdeckt
• Im Quelltext-Editor auf "TForm" mit gedrücktem CTRL klicken. Dies öffnet die Unit forms.pp, und der Cursor steht auf der Deklaration von TForm. Im FPDoc-Fenster steht nun der (spärliche) Hilfetext zu TForm. In der Titelzeile von FPDoc steht der Pfad zur verwendeten forms.xml-Datei -- die ist wie schon angedeutet in (lazarus)\docs\xml\lcl.
• Gehe ich im Quelltext weiter und klicke auf TCustomForm, so wird man in der xml-Datei fündiger, Lasche "Description"
• Jede Änderung, die man im FPDoc-Fenster macht und speichert, wird sofort im Editorfenster in den Hilfe-Popups sichtbar. Toll!
• Weniger toll: FPDoc ist extrem pingelig mit der Formatierung der HTML-Texte und formatiert immer wieder um. Der Inhalt bleibt zwar bestehen, aber das ist extrem lästig, weil das Versionskontrollsystem mit unnötigen Änderungen überschwemmt wird.

Der übliche Weg, Änderungen an den xml-Dateien, auch für FPC, ins Produkt zu bekommen, ist einen Bug-Report zu schreiben. Durchsuche den Bugtracker nach Reports von dsiders als Vorlage.

Die von dir verwendete dateutils.xml gehört eigentlich zu FPC (RTL). Meines Wissens wird die RTL-Hilfe in Lazarus nur als kompiliertes CHM-Datei ausgeliefert. Das Vorgehen scheint mir hier nicht kompatibel zum oben beschriebenen Vorgehen bei Lazarus zu sein, möglicherweise die Ursache für deine Probleme? Vielleicht solltest du die Frage im englischen Forum oder, besser, auf der fpc-devel Mailinglist (https://lists.freepascal.org/cgi-bin/ma ... /fpc-devel) stellen, wo Michael Van Canneyt mitliest, er ist, soviel ich weiß, maßgeblich an den Hilfetexten beteiligt.

Was ich schon gemacht habe, ist, die Hilfe-Text von Packages einzubinden. Hier hat jedes Package in seinen Optionen eigene FPDoc-Einstellungen (unter "IDE-Einstellungen"). Damit kann man die in diesem Verzeichnis abgelegten xml-Dateien in der IDE anzeigen lassen, wenn die Maus über einen Bezeichner aus diesem Package fährt. Was NICHT geht, ist, dass eine aus diesem xml-Dateien per fpdoc generierte chm-Datei mit F1 angezeigt wird; das konnte mir bisher noch niemand erklären.

[wp_xyz]

Falls es dir nicht um fpdoc im Speziellen sondern um Dokumentationsmöglichkeiten deines Quellcodes im Allgemeinen geht, kann ich PasDoc (https://github.com/pasdoc/pasdoc/wiki) empfehlen. Ist aus meiner Sicht deutlich leichter zu benutzen und die Dokumentation wird direkt als Kommentar im Quellcode geschrieben.

So sehr bin ich von PasDoc nicht begeistert:

Kann man mit PasDoc auch die Popup-Hilfe-Text schreiben, die die IDE als MouseOver anzeigt?

Soviel ich weiß muss man die Hilfetexte im interface-Teil der Units unterbringen. Das zerstört die Lesbarkeit der Units erheblich. Besser wäre es, wenn man die Hilfe-Kommentare in den Implementation-Teil schreiben könnte.

Auch mit PasDoc wird das Problem nicht gelöst, dass man die erzeugten chm-Dateien nicht in die IDE einbinden kann, d.h. wenn man auf einem Schlüsselwort F1 drückt, passiert nichts.

[Socke]

Kann man mit PasDoc auch die Popup-Hilfe-Text schreiben, die die IDE als MouseOver anzeigt?

Die IDE zeigt dir die Kommentare über z.B. einer Methodendefinition an - unabhängig davon, ob diese PasDoc Markup enthalten oder nicht.

Soviel ich weiß muss man die Hilfetexte im interface-Teil der Units unterbringen. Das zerstört die Lesbarkeit der Units erheblich. Besser wäre es, wenn man die Hilfe-Kommentare in den Implementation-Teil schreiben könnte.

Im Interface-Teil sollte das Interface dokumentiert sein und im Implementation-Teil die Details zur Implementierung. Letzteres ist für einen anderen Entwickler nur von untergeordnetem Interesse.

[wp_xyz]

Kann man mit PasDoc auch die Popup-Hilfe-Text schreiben, die die IDE als MouseOver anzeigt?

Die IDE zeigt dir die Kommentare über z.B. einer Methodendefinition an - unabhängig davon, ob diese PasDoc Markup enthalten oder nicht.

Aber nicht die Kurz-Hilfe die in der xml-Datei enthalten ist. Bewege die Maus über "TButton" - dann erscheint nicht nur die Parameter-Liste sondern auch eine Beschreibung. Ich bezweifle, ob das bei den PasDoc-Hilfetexten auch der Fall ist.

Soviel ich weiß muss man die Hilfetexte im interface-Teil der Units unterbringen. Das zerstört die Lesbarkeit der Units erheblich. Besser wäre es, wenn man die Hilfe-Kommentare in den Implementation-Teil schreiben könnte.

Im Interface-Teil sollte das Interface dokumentiert sein und im Implementation-Teil die Details zur Implementierung. Letzteres ist für einen anderen Entwickler nur von untergeordnetem Interesse.

Der Interface-Teil ist der Teil der Unit, in dem alle Methoden etc kompakt aufgelistet sind. Das ist der ideale Platz etwas zu suchen (bitte verweise mich jetzt nicht auf die Hilfe-Datei, die im Zweifelsfall nicht aktuell ist), und wenn die einzelnen Einträge durch ellenlange Dokumentationskommentare auseinandergerissen sind, ist das extrem unübersichtlich.

[af0815]

Der Interface-Teil ist der Teil der Unit, in dem alle Methoden etc kompakt aufgelistet sind. Das ist der ideale Platz etwas zu suchen (bitte verweise mich jetzt nicht auf die Hilfe-Datei, die im Zweifelsfall nicht aktuell ist), und wenn die einzelnen Einträge durch ellenlange Dokumentationskommentare auseinandergerissen sind, ist das extrem unübersichtlich.

Das war, soweit ich mir das vor laaaanger Zeit erklären habe lassen, der Grund für fpdoc. Damit die Dokumentation nicht den Quelltext unlesbar macht. Ein Beispiel ist PascalScada was dadurch nicht gerade leicht zu lesen ist.

[m.fuchs]

Kann man mit PasDoc auch die Popup-Hilfe-Text schreiben, die die IDE als MouseOver anzeigt?

Das geschieht unabhängig von PasDoc. Für die Popup-Hilfe-Texte werde Kommentare die direkt vor dem Element stehen ausgelesen und angezeigt.

Soviel ich weiß muss man die Hilfetexte im interface-Teil der Units unterbringen. Das zerstört die Lesbarkeit der Units erheblich. Besser wäre es, wenn man die Hilfe-Kommentare in den Implementation-Teil schreiben könnte.

Das kann man auch: https://github.com/pasdoc/pasdoc/wiki/I ... entsOption

Man kann sogar externe Dateien verwenden, wenn man will (https://github.com/pasdoc/pasdoc/wiki/R ... onFromFile). Davon würde ich aber abraten. Aus meiner Sicht sollte die Dokumentation so nahe an der Definition des Quellcodes stehen wie möglich. Aber wenn dir das nicht gefällt gibt es eben auch die beiden anderen Optionen.

Auch mit PasDoc wird das Problem nicht gelöst, dass man die erzeugten chm-Dateien nicht in die IDE einbinden kann, d.h. wenn man auf einem Schlüsselwort F1 drückt, passiert nichts.

Das Problem löst kein Dokumentationssystem.

[m.fuchs]

Die IDE zeigt dir die Kommentare über z.B. einer Methodendefinition an - unabhängig davon, ob diese PasDoc Markup enthalten oder nicht.

Aber nicht die Kurz-Hilfe die in der xml-Datei enthalten ist. Bewege die Maus über "TButton" - dann erscheint nicht nur die Parameter-Liste sondern auch eine Beschreibung. Ich bezweifle, ob das bei den PasDoc-Hilfetexten auch der Fall ist

Wenn der PasDoc-Hilfetext über dem Element steht (Standardfall) dann schon.

[wp_xyz]

Klingt gut. Da bin ich bzgl. PasDoc offenbar nicht mehr auf dem Laufenden...

[braunbär]

Falls es dir nicht um fpdoc im Speziellen sondern um Dokumentationsmöglichkeiten deines Quellcodes im Allgemeinen geht, kann ich PasDoc (https://github.com/pasdoc/pasdoc/wiki) empfehlen. Ist aus meiner Sicht deutlich leichter zu benutzen und die Dokumentation wird direkt als Kommentar im Quellcode geschrieben.

Mir hätet der Ansatz von FPDoc mit einem Fenster in der IDE, bei dem automatisch die Hilfe zu einem Element angezeigt wird, wenn man den Cursor darauf posiitoniert, gut gefallen. Aber vor allem der Fehler, dass das Markieren von Text mit der Maus durch FPDoc immer wieder (unregelmäßig, aber doch recht häufig) gestört wird, hat mir inzwischen die Verwendung eigentlich wieder verleidet.

Ich werde mir jetzt pasdoc einmal genauer anschauen. Schön wäre es halt, wenn sich die Entwickler auf ein Tool einigen würden, mit dem dann auch die ganze Dokumentation von Free Pascal und Lazarus gebündelt wird. Da ist leider auch ein ziemlicher Wildwuchs.