Index: openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html,v diff -u -N -r1.2 -r1.2.2.1 --- openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html 27 Oct 2014 16:40:22 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html 22 Jun 2016 07:48:44 -0000 1.2.2.1 @@ -7,66 +7,66 @@

Using comments to document Tcl procedures

-Templating System +Templating System

Text divisions, grouping

-< blah blah > +< 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>
+# @namespace ... <other namespaces>
- +
@@ -77,9 +77,9 @@ guideline of how the markers guide parsing may help those documenting their own work:
-the @namespace marker +the @namespace marker -the @public/private markers +the @public/private markers -the directive markers
+the directive markers
The commentary text that precedes a Tcl proc command should contain a list of directives identified by these markers: 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, +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> +# @(param|option) <parameter name> {default <description of default value>} <description or explanation>
for required parameters:
-# @param <parameter name> <description or explanation> +# @param <parameter name> <description or explanation>
-Note that the literal curly brackets with the word default are required to include any +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 +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 @@ -158,9 +158,9 @@ 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: +On to @see directive markers:

-# @see <type of reference> <name of reference> <url of reference> +# @see <type of reference> <name of reference> <url of reference>
Indicating the url of the reference is made somewhat simple because all namespaces will @@ -170,12 +170,12 @@ 

 # @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_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 +url value is optional as long as you use the full and completely qualified name of the namespace or procedure.