Index: openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp,v
diff -u -r1.2.2.1 -r1.2.2.2
--- openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 25 Aug 2015 18:02:14 -0000 1.2.2.1
+++ openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 9 Jun 2016 13:03:12 -0000 1.2.2.2
@@ -3,56 +3,56 @@
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:
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
- -
\@namespace
is used to indicate the starting +\@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 markersthe directive 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 @@ -80,7 +80,7 @@ out as commentary text; all text after theproc
command but before the next\@private
or\@public
marker is recorded as source code
+
The commentary text that precedes a Tclproc
command 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
\@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 +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, and
granter_id
andprivilege_id
would 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_chicken
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.
templating\@arsdigita.com