ACS Documentation : ACS Core Architecture Guide : Documenting Tcl Files
In versions of the ACS 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:
In addition, the inputs expected by a Tcl page (i.e., form variables) would be enumerated in a call to# # path from server home/filename # # Brief description of the file's purpose # # author's email address, file creation date # # $Id$ #
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 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 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/
).
ad_page_contract
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
:
Note that:# /packages/acs-core/api-doc/www/package-view.tcl ad_page_contract { version_id:integer public_p:optional kind { format "html" } } { Shows APIs for a particular package. @param version_id the ID of the version whose API to view. @param public_p view only public APIs? @param kind view the type of API to view. One of <code>procs_files</code>, <code>procs</code>, <code>content</code>, <code>types</code>, or <code>gd</code>. @param format the format for the documentation. One of <code>html</code> or <code>xml</code>. @author Jon Salz (jsalz@mit.edu) @creation-date 3 Jul 2000 @cvs-id tcl-documentation.html,v 1.3 2000/07/06 05:59:06 michael Exp }
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 corresponding Tcl variables when the page is
executed.
proc
(a two-element list where the first element is the parameter
name and the second argument is the default value).
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 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 return true).
trim
: the argument will be [string trim]'ed.
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 contract, and the query string is
then?dest_user_id=913&dest_user_id=891&dest_user_id=9
$dest_user_id
is set to [list 913 891 9]
.
array
: the argument may be specified arbitrarily many
times in the query string, with parameter names with 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 contract, and the query string is
then?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
$dest_user_id
is set to [list 913 891 9]
.
@
). You are encouraged to provide:
@param
tag for each allowable query argument.
The format is
@param parameter-name description...
@author
tag for each author. Specify the author's
name, followed his or her email address in parentheses.
@creation-date
tag indicating when the script was
first created.
@cvs-id
tag containing the page's CVS identification
string. Just use tcl-documentation.html,v 1.3 2000/07/06 05:59:06 michael Exp
when creating the file, and CVS will substitute
an appropriate string when you check the file in.
@
tags are optional, but highly recommended!
ad_library
Syntaxad_library
provides a replacement for the informal documentation (described
above) found at the beginning of every Tcl page. Instead of:
you'll now write:# /packages/acs-core/00-proc-procs.tcl # # Routines for defining procedures and libraries of procedures (-procs.tcl files). # # jsalz@mit.edu, 7 Jun 2000 # # tcl-documentation.html,v 1.3 2000/07/06 05:59:06 michael Exp
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 (# /packages/acs-core/00-proc-procs.tcl ad_library { Routines for defining procedures and libraries of procedures (<code>-procs.tcl</code> files). @creation-date 7 Jun 2000 @author Jon Salz (jsalz@mit.edu) @cvs-id tcl-documentation.html,v 1.3 2000/07/06 05:59:06 michael Exp }
@
). HTML formatting is allowed. You are encouraged to provide:
@author
tag for each author. Specify the author's
name, followed his or her email address in parentheses.
@creation-date
tag indicating when the script was
first created.
@cvs-id
tag containing the page's CVS identification
string. Just use tcl-documentation.html,v 1.3 2000/07/06 05:59:06 michael Exp
when creating the file, and CVS will substitute
an appropriate string when you check the file in.