Documentation Comment

Anwendungen, Tools, Userlibs und anderes nützliches.
Benutzeravatar
RSBasic
Admin
Beiträge: 8022
Registriert: 05.10.2006 18:55
Wohnort: Gernsbach
Kontaktdaten:

Documentation Comment

Beitrag von RSBasic »

Hallo :)

Mit diesem Werkzeug ist es möglich, die eigenen Prozeduren, die einzelnen Parameter und den Rückgabewert wie in C# zu dokumentieren.
Die Beschreibungen werden automatisch im PB-Editor angezeigt, wenn man einen Prozeduraufruf schreibt oder in die Parameterliste klickt.

Screenshot:
Bild

Wie funktioniert es?
Vor einer Prozedur erstellt man folgende Kommentare:

Code: Alles auswählen

;<comment>
;  <summary>Meine Funktionsbeschreibung...</summary>
;  <param>Parameter1: Beschreibung des ersten Parameters</param>
;  <param>Parameter2: Beschreibung des zweiten Parameters</param>
;  <param>Parameter3: Beschreibung des dritten Parameters</param>
;  <return>Beschreibung des Rückgabewertes</return>
;  <example>MeineFunktion(1, 2, "Hello")</example>
;</comment>
Procedure MeineFunktion(Parameter1, Parameter2.i, Parameter3.s)
;...
";<comment>" und ";</comment>" können im PB-Einstellungsfenster als Faltmarken hinzugefügt und ausgeblendet werden.

Diese Kommentare werden von meinem Werkzeug automatisch ermittelt (spätestens nach 3 Sekunden) und angezeigt, wenn man einen Prozeduraufruf schreibt oder in die Parameterliste klickt.

In den Kommentaren können folgende Formatierungen benutzt werden:
  • <b>Text</b>: Fett
  • <i>Text</i>: Kursiv
  • <u>Text</u>: Unterstrichen
  • <s>Text</s>: Durchgestrichen
  • <sup>Text</sup>: Hochgestellt
  • <sub>Text</sub>: Tiefgestellt
  • https://www.rsbasic.de: Klickbarer Web-Link
  • file:///C:\...\Info.txt: Klickbarer Datei-Link (Hinweis: Pfad mit Leerzeichen bitte "%20" benutzen)
  • <br>: Zeilenumbruch
Installation:
Bild

Voraussetzungen:
Die Einstellung "Vollständigen Quellcode-Pfad in der Titelzeile anzeigen" muss aktiviert sein, weil ich keine andere Möglichkeit habe, den Pfad zur PB-Datei zu ermitteln.

Download: https://www.rsbasic.de/downloads/downlo ... omment.zip
Bild

Ich würde mich über Feedbacks, Verbesserungsvorschläge, Fehlermeldungen oder Wünsche sehr freuen. Danke :)
Aus privaten Gründen habe ich leider nicht mehr so viel Zeit wie früher. Bitte habt Verständnis dafür.
Bild
Bild
Benutzeravatar
Kiffi
Beiträge: 10621
Registriert: 08.09.2004 08:21
Wohnort: Amphibios 9

Re: Documentation Comment

Beitrag von Kiffi »

Hammer! :allright:

Ich bin in letzter Zeit verstärkt mit B4J unterwegs und die IDE unterstützt das auch. Sehr nützlich.

Eine Anmerkung:

Es scheint wohl Probleme mit Umlauten zu geben:

Bild


Unschönheit:

Das Hilfe-Fenster sollte sich schließen, wenn man im Code mit dem Mausrad scrollt.


Tüpfelchen auf dem ı:

In B4J kann man auch einen Bereich angeben, in dem man einen kleinen Beispiel-Schnippsel eintragen kann. Mit Klick auf 'Copy' wird dieser dann in die Zwischenablage gespeichert und man kann ihn dann im Editor einfügen;

Bild

Bild

Danke & Grüße ... Peter
Hygge
Benutzeravatar
RSBasic
Admin
Beiträge: 8022
Registriert: 05.10.2006 18:55
Wohnort: Gernsbach
Kontaktdaten:

Re: Documentation Comment

Beitrag von RSBasic »

Documentation Comment 1.0.1 wurde veröffentlicht.

Changelog:
  • Hinzugefügt: "<example" wurde hinzugefügt, um für die eigene Funktion einen Beispielcode zum Einfügen bereitzustellen.
  • Bugfix: Summary-Fenster wird jetzt automatisch geschlossen, wenn gescrollt wird.
  • Bugfix: Umlautprobleme bei UTF8

Kiffi hat geschrieben:Ich bin in letzter Zeit verstärkt mit B4J unterwegs und die IDE unterstützt das auch. Sehr nützlich.
Ah, ich habe mich mal gefragt, was für IDEs es noch gibt, die sowas können, aber da fand ich nur Visual Studio.
Kiffi hat geschrieben:Es scheint wohl Probleme mit Umlauten zu geben:
Sollte behoben sein. Kannst du es bei dir auch nochmal testen?
Kiffi hat geschrieben:Das Hilfe-Fenster sollte sich schließen, wenn man im Code mit dem Mausrad scrollt.
Behoben
Kiffi hat geschrieben:In B4J kann man auch einen Bereich angeben, in dem man einen kleinen Beispiel-Schnippsel eintragen kann. Mit Klick auf 'Copy' wird dieser dann in die Zwischenablage gespeichert und man kann ihn dann im Editor einfügen;
Gute Idee, wurde umgesetzt. Da das ein EditorGadget ist, kann man den hinterlegten Beispielcode mit der Maus und Tastatur kopieren und einfügen.
Aus privaten Gründen habe ich leider nicht mehr so viel Zeit wie früher. Bitte habt Verständnis dafür.
Bild
Bild
Benutzeravatar
Kiffi
Beiträge: 10621
Registriert: 08.09.2004 08:21
Wohnort: Amphibios 9

Re: Documentation Comment

Beitrag von Kiffi »

RSBasic hat geschrieben:Ah, ich habe mich mal gefragt, was für IDEs es noch gibt, die sowas können, aber da fand ich nur Visual Studio.
Visual Studio Code kann ebenfalls (ist ja auch quasi aus dem selbem Haus ;-)).
RSBasic hat geschrieben:
Kiffi hat geschrieben:[...] Umlaute [...]
Sollte behoben sein.
yess! :D
RSBasic hat geschrieben:
Kiffi hat geschrieben:[...] Mausrad [...]
Behoben
Primstens. :D
RSBasic hat geschrieben:Da das ein EditorGadget ist, kann man den hinterlegten Beispielcode mit der Maus und Tastatur kopieren und einfügen.
Sauber, Danke! :allright:

ich habe jetzt mal ein wenig weiter probiert. Insgesamt scheint das Erstellen und Ausprobieren der Documentation-Fenster doch noch ein wenig hakelig zu sein. Mir scheint, als ob Du das Fenster erst gar nicht anzeigst, wenn die Documentation-Syntax nicht OK ist. Nach wiederholter Veränderung der Documentation erschien dann irgendwann auch mal das Fenster. Ich musste meinen Code allerdings zwischenzeitig mehrfach abspeichern. Änderungen in der Documenation werden auch nicht immer sofort übernommen (siehe das gif unten).

Und dann gibt es noch ein Positionierungsproblem des Fensters:

Bild

Grüße ... Peter
Hygge
Benutzeravatar
RSBasic
Admin
Beiträge: 8022
Registriert: 05.10.2006 18:55
Wohnort: Gernsbach
Kontaktdaten:

Re: Documentation Comment

Beitrag von RSBasic »

Kiffi hat geschrieben:Ich musste meinen Code allerdings zwischenzeitig mehrfach abspeichern. Änderungen in der Documenation werden auch nicht immer sofort übernommen (siehe das gif unten).
Es liegt daran:
RSBasic hat geschrieben:Damit mein Werkzeug alle erstellten Beschreibungskommentare aus allen PB-Dateien lesen kann, wird das ganze Projekt mit dem Compiler-Parameter "/PREPROCESS" im Temp-Verzeichnis in eine PB-Datei zusammengefasst, damit mein Werkzeug nicht alle Macros und Includes auflösen muss.
Leider erlaubt der Compiler-Parameter "/PREPROCESS" keine Syntax-Fehler. Aus dem Grund ist es wichtig, dass das Projekt ohne Syntax-Fehler kompilierbar ist, wenn man neue Beschreibungskommentare hinzufügen möchte.
Neue Summary-Änderung kann erst ausgelesen werden, wenn im Quellcode keine Syntax-Fehler gibt. Wenn du "Test(" entfernst und bis zu 3 Sekunden wartest, dann sollte die von dir geänderte Beschreibung gelesen und im Informationsfenster angezeigt werden.
Es ist aufgrund der Einschränkung des Compiler-Parameters "/PREPROCESS" leider nicht anders möglich, da dieser Parameter keine Syntax-Fehler zulässt, was meiner Meinung nach suboptimal ist bzw. nicht dafür zuständig sein sollte.
Die einzige Alternative wäre, wenn ich die Funktion "/PREPROCESS" nachbaue und alle Inkludes und Macros auflöse, um alle Dateien eines Projektes auszulesen.
Kiffi hat geschrieben:Und dann gibt es noch ein Positionierungsproblem des Fensters:
Kannst du mir bei deiner Testdatei ein paar Informationen geben wie z.B. ob Reintext oder UTF8 usw.? Danke im Voraus
Aus privaten Gründen habe ich leider nicht mehr so viel Zeit wie früher. Bitte habt Verständnis dafür.
Bild
Bild
Benutzeravatar
Sicro
Beiträge: 955
Registriert: 11.08.2005 19:08
Kontaktdaten:

Re: Documentation Comment

Beitrag von Sicro »

RSBasic hat geschrieben:Die einzige Alternative wäre, wenn ich die Funktion "/PREPROCESS" nachbaue und alle Inkludes und Macros auflöse, um alle Dateien eines Projektes auszulesen.
Es ist schon spät, aber: Ist es wirklich erforderlich, die Macros aufzulösen? Ich denke nicht. Und die Include-Befehle zu verarbeiten ist einfach…
Bild
Warum OpenSource eine Lizenz haben sollte :: PB-CodeArchiv-Rebirth :: Pleasant-Dark (Syntax-Farbschema) :: RegEx-Engine (kompiliert RegExes zu NFA/DFA)
Manjaro Xfce x64 (Hauptsystem) :: Windows 10 Home (VirtualBox) :: Neueste PureBasic-Version
Derren
Beiträge: 557
Registriert: 23.07.2011 02:08

Re: Documentation Comment

Beitrag von Derren »

f#@k yeah!
Is ja der Hammer.
Ich hatte bisher noch keine IDE, die das konnte. In meinem letzten großen Projekt, habe ich eine Art Lexer verwendet um ein automatisch generiertes Hilfedokument zu erstellen, aber in "Echtzeit" in der IDE ist natürlich noch viel besser!

edit: Was Sicro sagt, ergibt eigentlich Sinn. So kann man auch Macros erstellen und dokumentieren, was ja nicht geht, wenn du sie vorher auflöst.
Signatur und so
Benutzeravatar
Josh
Beiträge: 1028
Registriert: 04.08.2009 17:24

Re: Documentation Comment

Beitrag von Josh »

Derren hat geschrieben:Was Sicro sagt, ergibt eigentlich Sinn. So kann man auch Macros erstellen und dokumentieren, was ja nicht geht, wenn du sie vorher auflöst.
Es geht nicht darum, dass RSBasic in deinem Sourcecode was ändert, es geht nur darum was notwendig wäre um /PREPROCESS nachzubilden.

Was Sicro schreibt macht übrigens überhaupt keinen Sinn, alleine die Includes zu verarbeiten ist nicht gerade trival. Wenn du /PREPROCESS kugelsicher nachbilden willst, dann bist du wahrscheinlich bei 50k Programmzeilen.
IB-Software
Beiträge: 57
Registriert: 29.08.2004 11:05
Computerausstattung: Windows 11
Wohnort: Berlin
Kontaktdaten:

Re: Documentation Comment

Beitrag von IB-Software »

Die Anzeige erfolgt nur, wenn der Procedurename auch mit richtiger Groß/Kleinschrift erfolgt.
PureBasic 5.73/6.04 Beta 2; Windows 11 Pro 64
Intel(R) Core(TM) i7-8700 CPU @ 3.20GHz 3.19 GHz 16GB; NVIDIA GeForce RTX 3060 16GB
Benutzeravatar
RSBasic
Admin
Beiträge: 8022
Registriert: 05.10.2006 18:55
Wohnort: Gernsbach
Kontaktdaten:

Re: Documentation Comment

Beitrag von RSBasic »

Documentation Comment 1.0.2 wurde veröffentlicht.

Changelog:
  • Geändert: Keine Groß- und Kleinschreibung
IB-Software hat geschrieben:Die Anzeige erfolgt nur, wenn der Procedurename auch mit richtiger Groß/Kleinschrift erfolgt.
Erledigt
Aus privaten Gründen habe ich leider nicht mehr so viel Zeit wie früher. Bitte habt Verständnis dafür.
Bild
Bild
Antworten