One undocumented feature in GCGB since about 2011, which I think needs to be documented, is the ability to read some extra information from comments in libraries. Some comments that start with ''' have a special meaning, and will be displayed as tooltips or as information to the user. This helps even inexperienced users to use extra libraries.
First, a note on comments in general. GCGB uses ; to indicate comments that it has placed automatically, and ' to indicate ones that the user has placed. When loading a program, it will not load any that start with ;. This shouldn't matter too much, but just something to be aware of.
As for code documentation comments, GCGB will load information about subroutines/functions and any hardware settings that need to be set.
For subroutines, a line before the Sub or Function line that starts with ''' will be used as a tooltip when the user hovers over the icon. A line that starts with '''@ will be interpreted differently, depending on what comes after the @.
'''@param ParamName Parameter Description
will add a description for the parameter. For a subroutine, this will show in the Icon Settings panel under the parameter when the user has selected that icon. For a function, it will show at the appropriate time in the Parameter Editor wizard.
'''@return Returned value
applies to functions only. It will be displayed in the Parameter Editor wizard when the user is asked to choose a function. An example of all this is given in srf04.h:
'''Read the distance to the nearest object
'''@param US_Sensor Sensor to read (1 to 4)
'''@return Distance in cm
Function USDistance(US_Sensor) As Word
If a subroutine or command is used internally in the library, but GCGB users shouldn't see it, it can be hidden by placing '''@hide before the Sub or Function line. Another example from srf04.h:
'''@hide
Sub InitUSSensor
These should hopefully be pretty easy to add. For anyone more motivated, it's also possible to add Hardware Settings. A particular setting can be defined anywhere in the file, using this syntax:
'''@hardware condition, display name, constant, value type
condition tells GCGB when to show the setting. Normally, this is All, but sometimes it can include a constant, a space and then a comma separated list of values. display name is a friendly name for the setting to display. constant is the constant that must be set, and value type is the type that will be accepted for that constant's value. To allow for multiple value types, enter a list of types with a | between them.
Allowed types are:
free - Allows anything
label - Allows any label
condition - Allows a condition
table - Allows a data table
bit - Allows any bit from variable, or bit variable
io_pin - Allows an IO pin
io_port - Allows an entire IO port
number - Allows any fixed number or variable
rangex:y - Allows any number between x and y
var - Allows any variable
var_byte - Allows any byte variable
var_word - Allows any word variable
var_integer - Allows any integer variable
var_string - Allows any string variable
const - Allows any fixed number
const_byte - Allows any byte sized fixed number
const_word - Allows any word sized fixed number
const_integer - Allows any integer sized fixed number
const_string - Allows any fixed string
byte - Allows any byte (fixed number or variable)
word - Allows any word
integer - Allows any integer
string - Allows any string
array - Allows any array
When the library is added the program, GCGB will show a new device with the name of the library file on the Hardware Settings window. The user can then set the relevant constants without necessarily needing to see any code.
(Note: adding a GCBASIC library to GCGB won't result in any changes to the library. GCGB uses the information it reads to help edit the user's program, but then the user's program is passed to the compiler along with the unchanged library.)
I'd appreciate it a lot if any new libraries posted here had some of these documentation comments in them. Hardware Settings are a bit more involved to add, but hopefully the bit of extra documentation for subroutines will be straight forward! (But I'm always happy to see more libraries, even if they don't have these comments!)
Another idea for the future is a small utility to turn these comments into some sort of HTML based documentation. Any thoughts on that?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
For the built in commands, and most of the stuff in the low level libraries, GCGB obtains information from the commands.dat file. But extra libraries can use these commands to extend GCGB.
There are some very nice new libraries in SVN and in this forum, which shouldn't need too much work. But yes, it would be good to double check everything before handing them over to less experienced users.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
One undocumented feature in GCGB since about 2011, which I think needs to be documented, is the ability to read some extra information from comments in libraries. Some comments that start with ''' have a special meaning, and will be displayed as tooltips or as information to the user. This helps even inexperienced users to use extra libraries.
First, a note on comments in general. GCGB uses ; to indicate comments that it has placed automatically, and ' to indicate ones that the user has placed. When loading a program, it will not load any that start with ;. This shouldn't matter too much, but just something to be aware of.
As for code documentation comments, GCGB will load information about subroutines/functions and any hardware settings that need to be set.
For subroutines, a line before the Sub or Function line that starts with ''' will be used as a tooltip when the user hovers over the icon. A line that starts with '''@ will be interpreted differently, depending on what comes after the @.
will add a description for the parameter. For a subroutine, this will show in the Icon Settings panel under the parameter when the user has selected that icon. For a function, it will show at the appropriate time in the Parameter Editor wizard.
applies to functions only. It will be displayed in the Parameter Editor wizard when the user is asked to choose a function. An example of all this is given in srf04.h:
If a subroutine or command is used internally in the library, but GCGB users shouldn't see it, it can be hidden by placing '''@hide before the Sub or Function line. Another example from srf04.h:
These should hopefully be pretty easy to add. For anyone more motivated, it's also possible to add Hardware Settings. A particular setting can be defined anywhere in the file, using this syntax:
condition tells GCGB when to show the setting. Normally, this is All, but sometimes it can include a constant, a space and then a comma separated list of values. display name is a friendly name for the setting to display. constant is the constant that must be set, and value type is the type that will be accepted for that constant's value. To allow for multiple value types, enter a list of types with a | between them.
Allowed types are:
free - Allows anything
label - Allows any label
condition - Allows a condition
table - Allows a data table
bit - Allows any bit from variable, or bit variable
io_pin - Allows an IO pin
io_port - Allows an entire IO port
number - Allows any fixed number or variable
rangex:y - Allows any number between x and y
var - Allows any variable
var_byte - Allows any byte variable
var_word - Allows any word variable
var_integer - Allows any integer variable
var_string - Allows any string variable
const - Allows any fixed number
const_byte - Allows any byte sized fixed number
const_word - Allows any word sized fixed number
const_integer - Allows any integer sized fixed number
const_string - Allows any fixed string
byte - Allows any byte (fixed number or variable)
word - Allows any word
integer - Allows any integer
string - Allows any string
array - Allows any array
When the library is added the program, GCGB will show a new device with the name of the library file on the Hardware Settings window. The user can then set the relevant constants without necessarily needing to see any code.
(Note: adding a GCBASIC library to GCGB won't result in any changes to the library. GCGB uses the information it reads to help edit the user's program, but then the user's program is passed to the compiler along with the unchanged library.)
I'd appreciate it a lot if any new libraries posted here had some of these documentation comments in them. Hardware Settings are a bit more involved to add, but hopefully the bit of extra documentation for subroutines will be straight forward! (But I'm always happy to see more libraries, even if they don't have these comments!)
Another idea for the future is a small utility to turn these comments into some sort of HTML based documentation. Any thoughts on that?
So, this enables/allow us to expand the functionality of GCGB? I did wonder how this worked.
We may need a quality review of files before we do a major drop!
For the built in commands, and most of the stuff in the low level libraries, GCGB obtains information from the commands.dat file. But extra libraries can use these commands to extend GCGB.
There are some very nice new libraries in SVN and in this forum, which shouldn't need too much work. But yes, it would be good to double check everything before handing them over to less experienced users.