Documentation Comment

Applications, Games, Tools, User libs and useful stuff coded in PureBasic
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Documentation Comment

Post 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:
Image

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:
Image

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
Image

I would be very pleased about feedbacks, improvement suggestions, error messages or wishes. Thanks :)
Image
Image
BarryG
Addict
Addict
Posts: 3292
Joined: Thu Apr 18, 2019 8:17 am

Re: Documentation Comment

Post 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.
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post 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
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post by RSBasic »

Documentation Comment 1.0.2 has been released.

Changelog:
  • Changed: Not case-sensitive
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post 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.
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post by RSBasic »

Documentation Comment 1.0.4 has been released.

Changelog:
  • Bugfixes: Umlauts are now always displayed correctly and other improvements.
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post 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.
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post by RSBasic »

Documentation Comment 1.0.6 has been released.

Changelog:
  • Bugfix: Additional spaces are no longer displayed during formatting.
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post by RSBasic »

Documentation Comment 1.0.7 has been released.

Changelog:
  • Bugfix
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post 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.
Image
Image
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post by RSBasic »

Documentation Comment 1.0.9 has been released.

Changelog:
  • Bugfix: File links (file:///...) are now correctly displayed and opened.
Image
Image
Dawgmann
User
User
Posts: 40
Joined: Wed Jul 17, 2019 5:32 pm

Re: Documentation Comment

Post 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?
User avatar
RSBasic
Moderator
Moderator
Posts: 1218
Joined: Thu Dec 31, 2009 11:05 pm
Location: Gernsbach (Germany)
Contact:

Re: Documentation Comment

Post by RSBasic »

Hello Dawgmann
Do you use project files? If yes, have you saved all project files?
What does your code look like?
Image
Image
Dawgmann
User
User
Posts: 40
Joined: Wed Jul 17, 2019 5:32 pm

Re: Documentation Comment

Post 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...
Dawgmann
User
User
Posts: 40
Joined: Wed Jul 17, 2019 5:32 pm

Re: Documentation Comment

Post 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.
Post Reply