Page 1 of 2
Documentation Comment
Posted: Sat Jun 22, 2019 9:08 am
by RSBasic
Hello
With this tool it is possible to document your own procedures, the individual parameters and the return value
as in C#.
The descriptions are automatically displayed in the PB editor when you write a procedure call or click in the parameter list.
Screenshot:
How does it work?
Before a procedure, you create the following comments:
Code: Select all
;<comment>
; <summary>My function description...</summary>
; <param>Parameter1: Description of the first parameter</param>
; <param>Parameter2: Description of the second parameter</param>
; <param>Parameter3: Description of the third parameter</param>
; <return>Description of the return value</return>
; <example>MyFunction(1, 2, "Hello")</example>
;</comment>
Procedure MyFunction(Parameter1, Parameter2.i, Parameter3.s)
;...
";<comment>" and ";</comment>" can be added and hidden as folding marks in the PB settings window.
These comments are automatically determined by my tool (after 3 seconds at the latest) and displayed when you write a procedure call or click in the parameter list.
The following formatting can be used in the comments:
- <b>Text</b>: Bold
- <i>Text</i>: Italic
- <u>Text</u>: Underlining
- <s>Text</s>: Strikethrough
- <sup>Text</sup>: Superscript
- <sub>Text</sub>: Subscript
- https://www.rsbasic.de: Clickable web link
- file:///C:\...\Info.txt: Clickable file link (Hint: Please use path with spaces "%20".)
- <br>: Line break
Installation:
Requirements:
The setting "Show full source path in title bar" must be enabled because I have no other way to find the path to the PB file.
Download: https://www.rsbasic.de/downloads/downlo ... omment.zip
I would be very pleased about feedbacks, improvement suggestions, error messages or wishes. Thanks
Re: Documentation Comment
Posted: Sat Jun 22, 2019 10:15 am
by BarryG
Nice implementation! I did something similar once, where I made a (since-deleted) tool that popped-up a procedure's first few lines in a MessageBox when I pressed a hotkey on its name. Nowhere near as cool as this one, though.
I really want Fred to make this sort of thing native.
Re: Documentation Comment
Posted: Sat Jun 22, 2019 4:48 pm
by RSBasic
Documentation Comment 1.0.1 has been released.
Changelog:
- Added: "<example" was added to provide an example code to insert for the own function.
- Bugfix: Summary window is now automatically closed when scrolling.
- Bugfix: Umlaut problems with UTF8
Re: Documentation Comment
Posted: Sun Jun 23, 2019 4:53 pm
by RSBasic
Documentation Comment 1.0.2 has been released.
Changelog:
- Changed: Not case-sensitive
Re: Documentation Comment
Posted: Mon Jul 08, 2019 2:37 pm
by RSBasic
Documentation Comment 1.0.3 has been released.
Changelog:
- Changed: Reading the summary comments now works without "/PREPROCESS". Thanks to Sicro for the Lexer and Parser.
Re: Documentation Comment
Posted: Mon Jul 15, 2019 8:41 pm
by RSBasic
Documentation Comment 1.0.4 has been released.
Changelog:
- Bugfixes: Umlauts are now always displayed correctly and other improvements.
Re: Documentation Comment
Posted: Tue Jul 16, 2019 12:33 pm
by RSBasic
Documentation Comment 1.0.5 has been released.
Changelog:
- Added: There are new settings in the settings file (AppData or program directory):
- InfoWindow_Color
- InfoWindow_ExampleColor
- InfoWindow_FontSize
- InfoWindow_BackColor
- Bugfix: Procedure names were always displayed in lower case.
Re: Documentation Comment
Posted: Tue Jul 16, 2019 4:14 pm
by RSBasic
Documentation Comment 1.0.6 has been released.
Changelog:
- Bugfix: Additional spaces are no longer displayed during formatting.
Re: Documentation Comment
Posted: Tue Jul 30, 2019 7:17 pm
by RSBasic
Documentation Comment 1.0.7 has been released.
Changelog:
Re: Documentation Comment
Posted: Sun Aug 25, 2019 2:25 pm
by RSBasic
Documentation Comment 1.0.8 has been released.
Changelog:
- Bugfix: Texts after a line break within the parameter description are now also indented.
Re: Documentation Comment
Posted: Mon Sep 02, 2019 11:39 am
by RSBasic
Documentation Comment 1.0.9 has been released.
Changelog:
- Bugfix: File links (file:///...) are now correctly displayed and opened.
Re: Documentation Comment
Posted: Thu Sep 05, 2019 2:18 am
by Dawgmann
I couldn't get this to work for me. I configured the tool as shown in the picture, but still no go.
Do you have a small instruction manual for it?
Re: Documentation Comment
Posted: Fri Sep 06, 2019 9:18 am
by RSBasic
Hello Dawgmann
Do you use project files? If yes, have you saved all project files?
What does your code look like?
Re: Documentation Comment
Posted: Sat Sep 07, 2019 6:57 pm
by Dawgmann
@RSBasic
I am using a project file (*.pbp) along with one source code file (*.pb) for testing. Here is the complete test code from the source file.
#MSG_CPTN = "My MsgBox Caption" ;Caption for the message box...
#MSG_VALU = 2 ;Value which corresponds to the desired message prompt...
#MSG_QDBL = chr(34) ;Double quotation mark...
; ==============================================================================
; Created By: B.B.S.
; Creation Date: <DD-MMM-YYYY>
; Revision Date: See Creation Date
; Dependencies: None
; Remarks: None
; ------------------------------------------------------------------------------
;<comment>
; <summary>Serves as the main procedure/function for, and directs the overall workflow of the program.</summary>
; <param>Choice: {Long Integer} Specifies which message prompt is to be returned.</param>
; <param>AddQuotes: {Boolean} Specifies whether to add quotation marks to the returned prompt.</param>
; <return>String value containing the message prompt.</return>
;</comment>
Procedure.s GetMessage(Choice.l, UseQuotes.b)
Protected strPmpt.s ;Retains the user-selected message prompt...
Select Case Choice ;Determine the user's input and assign the corresponding message prompt...
Case 1
strPmpt = "Hello World!"
Case 2
strPmpt = "PureBasic rocks!.!.!"
Case 3
strPmpt = "This is a test of the emergency broadcast system!"
Default
strPmpt = "I couldn't think of anything else stupid to say."
EndSelect
If UseQuotes = True ;If quotes are to be placed around the prompt...
strPmpt = #MSG_QDBL+strPmpt+#MSG_QDBL ;Add double quotation makrs to the prompt...
EndIf
ProcedureReturn strPmpt ;Return the specified message prompt...
EndProcedure
; ==============================================================================
; Created By: B.B.S.
; Creation Date: <DD-MMM-YYYY>
; Revision Date: See Creation Date
; Dependencies: None
; Remarks: None
; ------------------------------------------------------------------------------
;<comment>
; <summary>Serves as the main procedure/function for, and directs the overall workflow of the program.</summary>
; <param></param>
; <return></return>
;</comment>
Procedure Main()
Protected strRslt.s ;Retains the returned message prompt...
strRslt = GetMessage(#MSG_VALU) ;Retrieve the corresponding message prompt...
MessageRequester(#MSG_CPTN, strRslt) ;Display the specified promt in the message box...
EndProcedure
; ==============================================================================
; Created By: B.B.S.
; Creation Date: <DD-MMM-YYYY>
; Revision Date: See Creation Date
; Dependencies: None
; Remarks: None
; ------------------------------------------------------------------------------
;<comment>
; <summary>Serves as the entry point and exit point for the program.</summary>
; <param></param>
; <return></return>
;</comment>
If OpenConsole() ;If a console window is successfully created - begin the program...
Main() ;Call the main procedure...
Else ;If a console windows is not successfully created...
; ///////////////////////////////////
; INSERT ERROR HANDLING HERE!.!.!
; \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
EndIf
CloseConsole() ;Close the console window...
End ;Completely end program...
Re: Documentation Comment
Posted: Sat Sep 07, 2019 7:51 pm
by Dawgmann
@RSBasic
Okay... I got it working.
I have a decades-long habit of putting my source code file(s) in a subdirectory of the project folder (C:\%UserProfile%\Documents\PureBasic\MyProject_01\Source) rather than in the same directory as the project file, and the Documentation Comment program doesn't seem to like source files being in a different folder from the project file.
So, I moved my source file out of the source subfolder and back up into the "MyProject_01" folder with the project file. Everything appears to be working now.