Note that comment lines are indented to indicate the manner in @@ -62,15 +62,15 @@ more in depth guideline of how the markers guide parsing may help those documenting their own work:[------------------------------------------------------] -[------ 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> +# \@namespace ... <other namespaces>
-the \@namespace marker+the \@namespace marker
the directive markersthe \@public/private markers
- -
\@namespaceis used to indicate the starting +\@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 @@ -80,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:@@ -89,24 +89,24 @@ 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 +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 +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 +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 @@ -134,21 +134,21 @@ 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> ++optional as long as you use the full and completely +qualified name of the namespace or procedure.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