Commenting Tcl procedures for parsing

Using comments to document Tcl procedures

Templating System

Text divisions, grouping

< blah blah > The Tcl proc parser relies on three main text markers to divvy the Tcl library file into neat compartments: namespace, procedure and directive. Each of these divisions has its own text marker(s). In the end, your Tcl file should look something like this:




[------------------------------------------------------]
[------  ignored text at beginning of file  -----------]
[------------------------------------------------------]

# @namespace <name> <description of namespace>
	# <continued description>

	# @author <name of the primary author for this namespace>

	# @see <type of reference, like proc, namespace, url, or other> <full name of reference> <url of reference>
	# @see ... <more references>


   # (@public|@private) <name> <description of procedure>
     # <continued description>

     # @param <name> <default value> <description>
     # <continued description>

     # @param ... <info for other parameters>

     # @option <name> <default value> <description>
     # <continued description>

     # @option ... <info for other options>
 
     # @author <name of author>

     # @return <description of return variable>

     # @see <just like the namespace @see directive>

     [------------------------------------------------------]
     [----------  source text for procedure  ---------------] 
     [------------------------------------------------------]


   # @public or @private ... < more procedures within the same namespace >


# @namespace ... <other namespaces>

Note that comment lines are indented to indicate the manner in which they should be grouped only, and that there is no required spacing scheme for comments.

Use of these directive markers is largely straightforward, but a more in depth guideline of how the markers guide parsing may help those documenting their own work:

the @namespace marker

@namespace is used to indicate the starting point of all text -- code and comments -- related to the procedures contained within that namespace. All text between one @namespace marker and the next is parsed out as either Tcl proc source text or commentary of some sort

the body of text that falls between two @namespace markers is divided into sections identified by

the @public/private markers

although this convention is in no way enforced, each Tcl procedure should be prefaced with an @private marker if the procedure is meant only for internal package use, or with an @public marker if the proc is intended to be a CMA, ATS, or ACS Content Repository developer api

any text that falls between one @public/private marker and the next proc <procedure name> call will be parsed out as commentary text; all text after the proc command but before the next @private or @public marker is recorded as source code

the directive markers
The commentary text that precedes a Tcl proc command should contain a list of directives identified by these markers:

@author

@param

@option

@return

@see

The parser requires no specified ordering or grouping of these directives. Note: there should be one @param or @option directive marker for each parameter and option accepted by Tcl procedure. For the @option and @parameter markers, please follow one of the following formats, depending on whether or not the parameter or option you are detailing has a default value:
with a default value:
# @(param|option) <parameter name> {default <description of default value>} <description or explanation>
for required parameters:
# @param <parameter name> <description or explanation>

Note that the literal curly brackets with the word default are required to include any information about the option or parameter's default values. When default-value information is not included, the entry value will be marked as required if it is a parameter, or display no information if it is an option.
For example: the fictional procedure grant_permission might be preceded by these comments:
# @public grant_permission # checks for whether or not a user has the privilege # to manipulate an object in a specific manner # @param user_id id of the user to be granted the privilege # @param object_id id of the object which the user has been # granted privilege to manipulate # @param privilege_id {default defaults to read-write-edit on the object} # id of the privilege specifying # what actions the user can perform upon the object # @option granter_id {default taken from the current user's id} id of the user granting the privilege # @option alert_admin_email email of an admin to be alerted # @see namespace util util.html
In the above example user_id and object_id would be marked as required, alert_admin_email would show no default-value description, and granter_id and privilege_id would show the the default info from above.
On to @see directive markers:
# @see <type of reference> <name of reference> <url of reference>
Indicating the url of the reference is made somewhat simple because all namespaces will be described within their own static html page, and all procedure information is anchor-referenced:
# @see namespace util util.html
# @see proc template::multirow::create multirow.html#template::multirow::create
# @see url <a picture of wally my dog> http://my.page.net/dogs/wally.jpg
# @see proc doc::util::eat_chicken
If you are referring to a namespace or procedure (use proc for the reference type), the url value is optional as long as you use the full and completely qualified name of the namespace or procedure.