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.3 --- 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 7 Aug 2017 23:48:03 -0000 1.3 @@ -7,66 +7,66 @@
-
+
[------------------------------------------------------]
-[------ 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 markerIf you are referring to a namespace or procedure (use-
-the @public/private markers +the @public/private markers@namespace
is used to indicate the starting point of all text +- @@ -88,7 +88,7 @@ sections identified by
@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 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, @@ -101,7 +101,7 @@
+the directive markers
The commentary text that precedes a Tclproc
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
- @@ -112,22 +112,22 @@
@author
@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:-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 required parameters:# @(param|option) <parameter name> {default <description of default value>} <description or explanation>
+# @(param|option) <parameter name> {default <description of default value>} <description or explanation>
-# @param <parameter name> <description or explanation>
+# @param <parameter name> <description or explanation>
For example: the fictional procedure grant_permission might be preceded by @@ -158,9 +158,9 @@
alert_admin_email
would show no default-value description, andgranter_id
andprivilege_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,18 +170,18 @@# @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
+url value is optional as long as you use the full and completely qualified name of
the namespace or procedure.