Documenting Tcl Files: Page Contracts and Libraries

by Jon Salz on 3 July 2000

ACS Documentation : ACS Core Architecture Guide : Documenting Tcl Files


The Big Picture

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:


#
# path from server home/filename
#
# Brief description of the file's purpose
#
# author's email address, file creation date
#
# $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, 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:

This has the following benefits:

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:

# /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
}
Note that:

ad_library Syntax

ad_library provides a replacement for the informal documentation (described above) found at the beginning of every Tcl page. Instead of:
# /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
you'll now write:
# /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

}
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 (@). HTML formatting is allowed. You are encouraged to provide:
jsalz@mit.edu