<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Documenting Tcl Files: Page Contracts and Libraries</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div><div class="authorblurb"><p>
by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> on 3 July 2000
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div><p>In versions of the OpenACS prior to 3.4, <a href="/doc/standards" target="_top">the standard
place</a> to document Tcl files (both Tcl pages and Tcl library files) was in
a comment at the top of the file:</p><pre class="programlisting">
#
# <span class="emphasis"><em>path from server home</em></span>/<span class="emphasis"><em>filename</em></span>
#
# <span class="emphasis"><em>Brief description of the file's purpose</em></span>
#
# <span class="emphasis"><em>author's email address</em></span>, <span class="emphasis"><em>file creation date</em></span>
#
# <a href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id: tcl-doc.html,v 1.12 2003/08/20 16:20:17 joela Exp $</a>
#
</pre><p>
In addition, the inputs expected by a Tcl page (i.e., form variables) would
be enumerated in a call to <tt>ad_page_variables</tt>, in effect,
documenting the page's argument list.
</p><p>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:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><tt><a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></tt></span>: Every Tcl page
has a <span class="strong">contract</span> that explicitly defines what inputs the page
expects (with more precision than <tt>ad_page_variables</tt>) and
incorporates metadata about the page (what used to live in the top-of-page
comment). Like <tt>ad_page_variables</tt>, <tt>ad_page_contract</tt>
also sets the specified variables in the context of the Tcl page.</p></li><li><p><span class="strong"><tt><a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library">ad_library</a></tt></span>: To be
called at the top of every library file (i.e., all files in the
<tt>/tcl/</tt> directory under the server root and
<tt>*-procs.tcl</tt> files under <tt>/packages/</tt>).</p></li></ul></div><p>
This has the following benefits:
</p><div class="itemizedlist"><ul type="disc"><li><p>Facilitates automatic generation of human-readable documentation.</p></li><li><p>Promotes security, by introducing a standard and automated way to check
inputs to scripts for correctness.</p></li><li><p>Allows graphical designers to determine easily how to customize
sites' UIs, e.g., what properties are available in templates.</p></li><li><p>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.)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div><p>
Currently <tt>ad_page_contract</tt> serves mostly as a replacement for
<tt>ad_page_variables</tt>. 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
<tt>ad_page_contract</tt> a newer, better, documented
<tt>ad_page_variables</tt>.)
</p><p>Let's look at an example usage of <tt>ad_page_contract</tt>:</p><pre class="programlisting">
# /packages/acs-kernel/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 $Id: tcl-doc.html,v 1.12 2003/08/20 16:20:17 joela Exp $
}
</pre><p>
Note that:
</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">By convention, <tt>ad_page_contract</tt> should be preceded
by a comment line containing the file's path</span>. The comment is on
line 1, and the contract starts on line 2.
</p></li><li><p><span class="strong"><tt>ad_page_contract</tt></span>'s first argument is
the list of expected arguments from the HTTP query (<tt>version_id</tt>,
<tt>public_p</tt>, <tt>kind</tt>, and <tt>format</tt>). Like
<tt>ad_page_variables</tt>, <tt>ad_page_contract</tt> sets the
corresponding Tcl variables when the page is executed.
</p></li><li><p><span class="strong">Arguments can have defaults</span>, specified using the same
syntax as in the Tcl <tt>proc</tt> (a two-element list where the first
element is the parameter name and the second argument is the default value).
</p></li><li><p><span class="strong">Arguments can have flags</span>, specified by following the
name of the query argument with a colon and one or more of the following
strings (separated by commas): </p><div class="itemizedlist"><ul type="circle"><li><p><span class="strong"><tt>optional</tt></span>: 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
<tt>public_p</tt> in the query, then in the page body <tt>[info exists
public_p]</tt> will return 0.
</p></li><li><p><span class="strong"><tt>integer</tt></span>: the argument must be an integer
(<tt>ad_page_contract</tt> 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.
</p></li><li><p><span class="strong"><tt>sql_identifier</tt></span>: the argument must be a SQL
identifier (i.e., <tt>[string is wordchar $the_query_var]</tt> must
return true).
</p></li><li><p><span class="strong"><tt>trim</tt></span>: the argument will be [string
trim]'ed.
</p></li><li><p><span class="strong"><tt>multiple</tt></span>: 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 <tt>-multiple-list</tt> flag to
<tt>ad_page_variables</tt>, and is useful for handling form input
generated by <tt><SELECT MULTIPLE></tt> tags and checkboxes. </p><p>For instance, if <tt>dest_user_id:multiple</tt> is specified in the
contract, and the query string is</p><pre class="programlisting">
?dest_user_id=913&dest_user_id=891&dest_user_id=9
</pre><p>
then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.
</p></li><li><p><span class="strong"><tt>array</tt></span>: the argument may be specified
arbitrarily many times in the query string, with parameter names with
suffixes like <tt>_1</tt>, <tt>_2</tt>, <tt>_3</tt>, etc. The
variable is set to a list of all those values (or an empty list if none are
specified). </p><p>For instance, if <tt>dest_user_id:array</tt> is specified in the
contract, and the query string is</p><pre class="programlisting">
?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
</pre><p>
then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.</p></li></ul></div></li><li><p><span class="strong">You can provide structured, HTML-formatted documentation for your
contract</span>. 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 (<tt>@</tt>). You are
encouraged to provide:
</p><div class="itemizedlist"><ul type="circle"><li><p>A description of the functionality of the page. If the description
contains more than one sentence, the first sentence should be a brief
summary.
</p></li><li><p>A <span class="strong"><tt>@param</tt></span> tag for each allowable query
argument. The format is </p><pre class="programlisting">
@param <span class="emphasis"><em>parameter-name</em></span> <span class="emphasis"><em>description...</em></span>
</pre></li><li><p>An <span class="strong"><tt>@author</tt></span> tag for each author. Specify the
author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><tt>@creation-date</tt></span> tag indicating when the
script was first created.</p></li><li><p>A <span class="strong"><tt>@cvs-id</tt></span> tag containing the page's CVS
identification string. Just use <tt>$Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $</tt> when creating the file, and CVS will
substitute an appropriate string when you check the file in.</p></li></ul></div><p>
These <tt>@</tt> tags are optional, but highly recommended!</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-ad-library"></a>ad_library</h3></div></div><p>
<tt>ad_library</tt> provides a replacement for the informal documentation
(described above) found at the beginning of every Tcl page. Instead of:
</p><pre class="programlisting">
# /packages/acs-kernel/00-proc-procs.tcl
#
# Routines for defining procedures and libraries of procedures (-procs.tcl files).
#
# jsalz@mit.edu, 7 Jun 2000
#
# $Id: tcl-doc.html,v 1.12 2003/08/20 16:20:17 joela Exp $
</pre><p>
you'll now write:
</p><pre class="programlisting">
# /packages/acs-kernel/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 $Id: tcl-doc.html,v 1.12 2003/08/20 16:20:17 joela Exp $
}
</pre><p>
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 (<tt>@</tt>). HTML formatting is allowed.
You are encouraged to provide:
</p><div class="itemizedlist"><ul type="disc"><li><p>An <span class="strong"><tt>@author</tt></span> tag for each author. Specify the
author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><tt>@creation-date</tt></span> tag indicating when the
script was first created.</p></li><li><p>A <span class="strong"><tt>@cvs-id</tt></span> tag containing the page's CVS
identification string. Just use <tt>$Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $</tt> when creating the file, and CVS will
substitute an appropriate string when you check the file in.</p></li></ul></div><div class="cvstag">($Id: tcl-doc.html,v 1.12 2003/08/20 16:20:17 joela Exp $)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Request Processor Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Bootstrapping OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tcl-doc.html#comments">View comments on this page at openacs.org</a></center></body></html>