It is currently Sun Nov 17, 2019 11:39 am

All times are UTC + 1 hour




Post new topic Reply to topic  [ 17 posts ]  Go to page 1, 2  Next
Author Message
 Post subject: Documentation Comment
PostPosted: Sat Jun 22, 2019 9:08 am 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
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:
;<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: http://www.rsbasic.de/downloads/downloa ... omment.zip
Image

I would be very pleased about feedbacks, improvement suggestions, error messages or wishes. Thanks :)

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Sat Jun 22, 2019 10:15 am 
Offline
Enthusiast
Enthusiast

Joined: Thu Apr 18, 2019 8:17 am
Posts: 390
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.


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Sat Jun 22, 2019 4:48 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
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

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Sun Jun 23, 2019 4:53 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Documentation Comment 1.0.2 has been released.

Changelog:
  • Changed: Not case-sensitive

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Mon Jul 08, 2019 2:37 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
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.

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Mon Jul 15, 2019 8:41 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Documentation Comment 1.0.4 has been released.

Changelog:
  • Bugfixes: Umlauts are now always displayed correctly and other improvements.

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Tue Jul 16, 2019 12:33 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
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.

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Tue Jul 16, 2019 4:14 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Documentation Comment 1.0.6 has been released.

Changelog:
  • Bugfix: Additional spaces are no longer displayed during formatting.

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Tue Jul 30, 2019 7:17 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Documentation Comment 1.0.7 has been released.

Changelog:
  • Bugfix

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Sun Aug 25, 2019 2:25 pm 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Documentation Comment 1.0.8 has been released.

Changelog:
  • Bugfix: Texts after a line break within the parameter description are now also indented.

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Mon Sep 02, 2019 11:39 am 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Documentation Comment 1.0.9 has been released.

Changelog:
  • Bugfix: File links (file:///...) are now correctly displayed and opened.

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Thu Sep 05, 2019 2:18 am 
Offline
User
User

Joined: Wed Jul 17, 2019 5:32 pm
Posts: 39
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?


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Fri Sep 06, 2019 9:18 am 
Offline
Moderator
Moderator
User avatar

Joined: Thu Dec 31, 2009 11:05 pm
Posts: 1106
Location: Germany::Berlin()
Hello Dawgmann
Do you use project files? If yes, have you saved all project files?
What does your code look like?

_________________
ImageImageImageImage Image


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Sat Sep 07, 2019 6:57 pm 
Offline
User
User

Joined: Wed Jul 17, 2019 5:32 pm
Posts: 39
@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...


Top
 Profile  
Reply with quote  
 Post subject: Re: Documentation Comment
PostPosted: Sat Sep 07, 2019 7:51 pm 
Offline
User
User

Joined: Wed Jul 17, 2019 5:32 pm
Posts: 39
@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.


Top
 Profile  
Reply with quote  
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 17 posts ]  Go to page 1, 2  Next

All times are UTC + 1 hour


Who is online

Users browsing this forum: No registered users and 5 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum

Search for:
Jump to:  

 


Powered by phpBB © 2008 phpBB Group
subSilver+ theme by Canver Software, sponsor Sanal Modifiye