In addition, the inputs expected by a Tcl page (i.e., form variables) would
be enumerated in a call to ad_page_variables, in effect,
-documenting the page's argument list.
+documenting the page's argument list.
The problem with these practices is that the documentation is only accessible by reading the source file itself. For this reason, ACS 3.4 introduces a new API for documenting Tcl files and, on top of that, a @@ -36,17 +36,17 @@ sites' UIs, e.g., what properties are available in templates.
Allows the request processor to be intelligent: a script can specify in its contract which type of abstract document it returns, and the request processor can transform it automatically into -something useful to a particular user agent. (Don't worry about this for -now - it's not complete for ACS 3.4.)
+something useful to a particular user agent. (Don't worry about this for +now - it's not complete for ACS 3.4.)
Currently ad_page_contract serves mostly as a replacement for
ad_page_variables. Eventually, it will be integrated closely
-with the documents API so that each script's contract will document
+with the documents API so that each script's contract will document
precisely the set of properties available to graphical designers in
-templates. (Document API integration is subject to change, so we don't
+templates. (Document API integration is subject to change, so we don't
decsribe it here yet; for now, you can just consider
ad_page_contract a newer, better, documented
ad_page_variables.)
-
Let's look at an example usage of ad_page_contract:
+Let's look at an example usage of
ad_page_contract:# /packages/acs-kernel/api-doc/www/package-view.tcl ad_page_contract { @@ -72,7 +72,7 @@Note that:
By convention,
ad_page_contractshould be preceded -by a comment line containing the file's path. The comment is on +by a comment line containing the file's path. The comment is on line 1, and the contract starts on line 2.
ad_page_contract's first argument is the list of expected arguments from the HTTP query (version_id, @@ -85,9 +85,9 @@Arguments can have flags, specified by following the name of the query argument with a colon and one or more of the following -strings (separated by commas):
optional: the query argument doesn't -need to be provided; if it's not, the variable for that argument simply -won't be set. For instance, if I call the script above without a +strings (separated by commas):
optional: the query argument doesn't +need to be provided; if it's not, the variable for that argument simply +won't be set. For instance, if I call the script above without apublic_pin the query, then in the page body[info exists public_p]will return 0.
integer: the argument must be an integer @@ -104,7 +104,7 @@
multiple: the argument may be specified arbitrarily many times in the query string, and the variable will be set to a -list of all those values (or an empty list if it's unspecified). This is +list of all those values (or an empty list if it's unspecified). This is analogous to the-multiple-listflag toad_page_variables, and is useful for handling form input generated by<SELECT MULTIPLE>tags and checkboxes.For instance, if
dest_user_id:multipleis specified in the @@ -128,7 +128,7 @@then
$dest_user_idis set to[list 913 891 9].You can provide structured, HTML-formatted documentation for your contract. Note that format is derived heavily from Javadoc: a -general description of the script's functionality, followed optionally by +general description of the script's functionality, followed optionally by a series of named attributes tagged by at symbols (
@). You are encouraged to provide:
A description of the functionality of the page. If the description @@ -141,8 +141,8 @@ @param parameter-name description...
An
@authortag for each author. Specify the -author's name, followed his or her email address in parentheses.A
@creation-datetag indicating when the -script was first created.A
@cvs-idtag containing the page's CVS +author's name, followed his or her email address in parentheses.A
@creation-datetag indicating when the +script was first created.A
@cvs-idtag containing the page's CVS identification string. Just use$Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $when creating the file, and CVS will substitute an appropriate string when you check the file in.@@ -160,7 +160,7 @@ # $Id$
-you'll now write: +you'll now write:
# /packages/acs-kernel/00-proc-procs.tcl @@ -177,12 +177,12 @@Note that format is derived heavily from Javadoc: a general description of -the script's functionality, followed optionally by a series of named +the script's functionality, followed optionally by a series of named attributes tagged by at symbols (
@). HTML formatting is allowed. You are encouraged to provide:
An
@authortag for each author. Specify the -author's name, followed his or her email address in parentheses.A
@creation-datetag indicating when the -script was first created.A
@cvs-idtag containing the page's CVS +author's name, followed his or her email address in parentheses.A
@creation-datetag indicating when the +script was first created.A
@cvs-idtag containing the page's CVS identification string. Just use$Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $when creating the file, and CVS will substitute an appropriate string when you check the file in.($Id$)View comments on this page at openacs.org