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 -r1.3
--- openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 27 Oct 2014 16:40:22 -0000 1.2
+++ openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 7 Aug 2017 23:48:03 -0000 1.3
@@ -1,72 +1,76 @@
- 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:Using comments to document Tcl procedures
Templating SystemText 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:
-
+# \@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>
-
-the \@namespace marker
+those documenting their own work:
+the \@namespace markerthe \@public/private markers
- -
\@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
+\@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 @@ -76,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 directive markers
The commentary text that precedes a Tclproc
command 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
\@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: +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, 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> +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 - +optional as long as you use the full and +completely qualified name of the namespace or +procedure.
+ \ No newline at end of file