The following conventions define the standard layout for every procedure in a module.

Each procedure is preceded by the procedure documentation, a series of Tcl comments that includes the following blocks. The documentation contains no blank lines, but each block is delimited with a line containing a single pound symbol (#) in the first column.

• Banner:  A Tcl comment that consists of 78 pound symbols (#) across the page.

• Title:  One line containing the routine name followed by a short, one-line description. The routine name in the title must match the declared routine name. This line becomes the title of automatically generated reference entries and indexes.

• Description:  A full description of what the routine does and how to use it.

• Synopsis:  The word SYNOPSIS: followed by a the synopsis of the procedure--its name and parameter list between .tS and .tE macros. Optional parameters are shown in square brackets. A variable list of arguments is represented by three dots (...).

• Parameters:  For each parameter, the .IP macro followed by the parameter name on one line, followed by its complete description on the next line. Include the default value and domain of definition in each parameter description.

• Returns:  The word RETURNS: followed by a description of the possible explicit result values of the subroutine (that is, values returned with the Tcl return command).

RETURNS: 
A list of 11 items: vxTicks taskId status priority pc sp errno 
timeout entry priNormal name

If the return value is meaningless enter N/A:

RETURNS: N/A

• Errors:  The word ERRORS: followed by all the error messages or error code (or both, if necessary) raised in the procedure by the Tcl error command.

ERRORS: 
"Cannot find symbol in symbol table"

If no error statement is invoked in the procedure, enter N/A.

ERRORS: N/A

The procedure documentation ends with an empty Tcl comment starting in column one.

The procedure declaration follows the procedure heading and is separated from the documentation block by a single blank line. The format of the procedure and parameter declarations is shown in A.6 Declaration Formats.

The following is an example of a standard procedure layout.

Example A-3:  Standard Tcl Procedure Layout

##################################################################### 
# 
# browse - browse an object, given its ID 
# 
# This routine is bound to the "Show" button, and is invoked when 
# that button is clicked.  If the argument (the contents of... 
# 
# SYNOPSIS 
# .tS 
# browse [objAddr | symbol | &symbol] 
# .tE 
# 
# PARAMETERS 
# .IP <objAddr> 
# the address of an object to browse 
# .IP <symbol> 
# a symbolic address whose contents is the address of 
# an object to browse 
# .IP <&symbol> 
# a symbolic address that is the address of an object to browse 
# 
# RETURNS: N/A 
# 
# ERRORS: N/A 
#

 
proc browse {args} { 
    ...  
}