+# \@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.+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 somthing like this: +[------------------------------------------------------] -[------ ignored text at beginning of file -----------] +[------ ignored text at beginning of file -----------] [------------------------------------------------------] -# \@namespace<name><description of namespace> - # <continued description> +# \@namespace<name><description of namespace> + # <continued description> - # \@author<name of the primary author for this namespace> + # \@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> + # \@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> + # (\@public|\@private) <name><description of procedure> + # <continued description> - # \@param<name><default value><description> - # <continued description> + # \@param<name><default value><description> + # <continued description> - # \@param ... <info for other paramaters> + # \@param ... <info for other paramaters> - # \@option<name><default value><description> - # <continued description> + # \@option<name><default value><description> + # <continued description> - # \@option ... <info for other options> + # \@option ... <info for other options> - # \@author<name of author> + # \@author<name of author> - # \@return<description of return variable> + # \@return<description of return variable> - # \@see<just like the namespace \@see directive> + # \@see<just like the namespace \@see directive> [------------------------------------------------------] - [---------- source text for procedure ---------------] + [---------- source text for procedure ---------------] [------------------------------------------------------] - # \@public or \@private ... < more procedures within the same namespace > + # \@public or \@private ... < more procedures within the same namespace > -# \@namespace ... <other namespaces> -
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+those documenting their own work: +
the directive markers+the \@namespace markerthe \@public/private markers
- -
\@namespaceis used to indicate the starting -point of all text -- code and comments -- related to the procedures -contained within that namespace. All text between one -\@namespacemarker 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+\@namespaceis used to indicate +the starting point of all text -- code and comments -- related to +the procedures contained within that namespace. All text between +one\@namespacemarker 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
-\@namespacemarkers is divided into sections identified by+
the \@public/private markersthe directive markers
- although this convention is in no way enforced, each Tcl procedure should be prefaced with an
-\@privatemarker if the procedure is meant only for internal package use, or with an @@ -76,7 +80,7 @@ out as commentary text; all text after theproccommand but before the next\@privateor\@publicmarker is recorded as source code
+
The commentary text that precedes a Tclproccommand should contain a list of directives identified by these markers:@@ -85,25 +89,25 @@ The parser requires no specified ordering or grouping of these directives. Note: there should be one
\@paramor\@optiondirective 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: +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|option) <parameter name> +{default <description of default value>} +<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. +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.# \@param <parameter name><description or explanation> +# \@param <parameter name><description or explanation>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 @@ -118,7 +122,7 @@ # 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 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 @@ -130,20 +134,23 @@ description, andgranter_idandprivilege_idwould show the the default info from above. -On to \@see directive markers:
# \@see <type of reference><name of -reference><url of reference> +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:If you are referring to a namespace or procedure (use# \@see namespace util util.html # \@see proc template::multirow::create multiow.html#template::multirow::create -# \@see url <a picture of wally my dog> http://my.page.net/dogs/wally.jpg +# \@see url <a picture of wally my dog> http://my.page.net/dogs/wally.jpg # \@see proc doc::util::eat_chickenprocfor the reference type), the url value is -optional as long as you use the full and completely -qualified name of the namespace or procedure.
templating\@arsdigita.com - +optional as long as you use the full and +completely qualified name of the namespace or +procedure.
+ \ No newline at end of file