Documenting Tcl Files: Page Contracts and Libraries

Prev	Chapter 13. Kernel Documentation	Next

By Jon Salz on 3 July 2000

+ +Documenting Tcl Files: Page Contracts and Libraries

Prev	Chapter 15. Kernel Documentation	Next

Documenting Tcl Files: Page Contracts and Libraries

By Jon Salz on 3 July 2000

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl

The Big Picture

In versions of the OpenACS prior to 3.4, the standard +

Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl

The Big Picture

In versions of the OpenACS prior to 3.4, the standard place to document Tcl files (both Tcl pages and Tcl library files) was in a comment at the top of the file:

 #
@@ -12,48 +12,48 @@
 #
 # author's email address, file creation date
 #
-# $Id$
+# $Id$
 #

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, +be enumerated in a call to ad_page_variables, in effect, 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 -web-based user interface for browsing the documentation:

ad_page_contract: Every Tcl page -has a contract that explicitly defines what inputs the page -expects (with more precision than ad_page_variables) and +web-based user interface for browsing the documentation:
- ad_page_contract: Every Tcl page +has a contract that explicitly defines what inputs the page +expects (with more precision than ad_page_variables) and incorporates metadata about the page (what used to live in the top-of-page -comment). Like ad_page_variables, ad_page_contract -also sets the specified variables in the context of the Tcl page.
- ad_library: To be +comment). Like ad_page_variables, ad_page_contract +also sets the specified variables in the context of the Tcl page.
- ad_library: To be called at the top of every library file (i.e., all files in the -/tcl/ directory under the server root and -*-procs.tcl files under /packages/).
+/tcl/ directory under the server root and +*-procs.tcl files under /packages/).

This has the following benefits: -

Facilitates automatic generation of human-readable documentation.
Promotes security, by introducing a standard and automated way to check -inputs to scripts for correctness.
Allows graphical designers to determine easily how to customize -sites' UIs, e.g., what properties are available in templates.
Allows the request processor to be intelligent: a script can specify in +
- Facilitates automatic generation of human-readable documentation.
- Promotes security, by introducing a standard and automated way to check +inputs to scripts for correctness.
- Allows graphical designers to determine easily how to customize +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.)

ad_page_contract

-Currently ad_page_contract serves mostly as a replacement for -ad_page_variables. Eventually, it will be integrated closely +now - it's not complete for ACS 3.4.)

ad_page_contract

+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 precisely the set of properties available to graphical designers in 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:

+ad_page_contract a newer, better, documented
+ad_page_variables.) 
+
Let's look at an example usage of ad_page_contract:
 
 # /packages/acs-kernel/api-doc/www/package-view.tcl
 ad_page_contract {
     version_id:integer
     public_p:optional
     kind
-    { format "html" }
+    { format "html" }
 } {
     Shows APIs for a particular package.
 
@@ -71,83 +71,83 @@
 
 

 Note that: 
-
By convention, ad_page_contract should be preceded
-by a comment line containing the file's path. The comment is on
+
By convention, ad_page_contract should be preceded
+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,
-public_p, kind, and format). Like
-ad_page_variables, ad_page_contract sets the
+
ad_page_contract's first argument is
+the list of expected arguments from the HTTP query (version_id,
+public_p, kind, and format). Like
+ad_page_variables, ad_page_contract sets the
 corresponding Tcl variables when the page is executed.
-
Arguments can have defaults, specified using the same
-syntax as in the Tcl proc (a two-element list where the first
+
Arguments can have defaults, specified using the same
+syntax as in the Tcl proc (a two-element list where the first
 element is the parameter name and the second argument is the default value).
 
-
Arguments can have flags, specified by following the
+
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
+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
-public_p in the query, then in the page body [info exists
-public_p] will return 0.
-
integer: the argument must be an integer
-(ad_page_contract will fail and display and error if not). This
+public_p in the query, then in the page body [info exists
+public_p] will return 0.
+
integer: the argument must be an integer
+(ad_page_contract will fail and display and error if not). This
 flag, like the next, is intended to prevent clients from fudging query
 arguments to trick scripts into executing arbitrary SQL. 
 
-
sql_identifier: the argument must be a SQL
-identifier (i.e., [string is wordchar $the_query_var] must
+
sql_identifier: the argument must be a SQL
+identifier (i.e., [string is wordchar $the_query_var] must
 return true). 
 
-
trim: the argument will be [string
+
trim: the argument will be [string
 trim]'ed. 
 
-
multiple: the argument may be specified
+
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
-analogous to the -multiple-list flag to
-ad_page_variables, and is useful for handling form input
-generated by <SELECT MULTIPLE> tags and checkboxes. 
For instance, if dest_user_id:multiple is specified in the
+analogous to the -multiple-list flag to
+ad_page_variables, and is useful for handling form input
+generated by <SELECT MULTIPLE> tags and checkboxes. 
For instance, if dest_user_id:multiple is specified in the
 contract, and the query string is
 
 ?dest_user_id=913&dest_user_id=891&dest_user_id=9
 
 

-then $dest_user_id is set to [list 913 891 9].
+then $dest_user_id is set to [list 913 891 9].
 
 
-
array: the argument may be specified
+
array: the argument may be specified
 arbitrarily many times in the query string, with parameter names with
-suffixes like _1, _2, _3, etc. The
+suffixes like _1, _2, _3, etc. The
 variable is set to a list of all those values (or an empty list if none are
-specified). 
For instance, if dest_user_id:array is specified in the
+specified). 
For instance, if dest_user_id:array is specified in the
 contract, and the query string is
 
 ?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
 
 

-then $dest_user_id is 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
+then $dest_user_id is 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
-a series of named attributes tagged by at symbols (@). You are
+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
+
A description of the functionality of the page. If the description
 contains more than one sentence, the first sentence should be a brief
 summary. 
 
-
A @param tag for each allowable query
+
A @param tag for each allowable query
 argument. The format is 
 
 @param parameter-name description...
 
-
An @author tag for each author. Specify the
-author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the
-script was first created.
A @cvs-id tag 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
+

An @author tag for each author. Specify the +author's name, followed his or her email address in parentheses.

A @creation-date tag indicating when the +script was first created.

A @cvs-id tag 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.

- These @ tags are optional, but highly recommended!

ad_library

-ad_library provides a replacement for the informal documentation + These @ tags are optional, but highly recommended!

Prev	Home	Next
Request Processor Design	Up	Bootstrapping OpenACS