CCP4i: Graphical User Interface
	Documentation for Programmers

How to document core CCP4i commands

• Introduction
• Doc Comment Tags
  • Overview
  • Documenting individual commands
  • Documenting groups of commands
• Examples
• Usage of the create_docs script

Introduction

Documentation for the core CCP4i commands is generated from the Tcl source code by running a script called create_docs. This script scans the Tcl source code files and builds HTML documentation in the $CCP4I_TOP/help/programmers/progdocs directory, based on the Tcl procedure definitions plus any doc comments tags written by the programmer within the source code file.

This document outlines how to add doc comments to Tcl source code so that useful HTML documentation can be generated. Information on the usage of the create_docs script can be found below.

Doc Comment Tags

Overview

The doc comments are based on a set of tags within Tcl comments in the source code. These tags are placed in particular parts of the source code and have their own syntax and meaning.

In this document bold text indicates the name of a doc comment tag and italicized text indicates the option text that follows it.

Each doc comment tag is terminated by a newline (so all other whitespace is ignored). If you wish to write a comment line which is longer than a "physical" line, then use the Tcl continuation character "\". (Note that the next line after the "\" character doesn't have to start with a comment character "#" - the line is still treated as part of the comment.)

There are currently two sets of tags, which are explained below:

• Documenting individual commands
• Documenting groups of commands

There are also some examples of usage.

Documenting individual commands

The following tags are used to provide information on the arguments and function for individual commands, which are defined as Tcl procedures.

#d_sum Summary text

A single line of text which concisely summarises the purpose of the command.

#d_desc Description of the command function

This is a longer description of the command which should include how it functions and what it returns, plus any additional information which might be useful in explaining how the command should be used (for example, its relationship with other commands).

Multiple #d_desc tags can be used - each tag creates a new paragraph in the HTML document.

#d_arg parameter_name Description of the parameter

This tag documents each of the compulsory arguments of the command.

There should be one #d_arg tag for each parameter in the argument list of the command which is explicitly defined. The first word after the #d_arg tag is the parameter name as it appears in the argument list of the proc command, and the remaining text is a brief description of the parameter.

Multiple #d_arg tags can be used (one for each argument).

#d_opt0 argument_name
#d_opt1 Description of the function of the argument

These tags appear in pairs and document each of the optional arguments of the command.

There should be one #d_opt0 tag for each optional argument, immediately followed by the #d_opt1 tag which provides a brief description of the parameter's function.

Multiple #d_opt0/#d_opt1 tag pairs can be used (one for each argument).

Documenting groups of commands

The following tags are used at the head of a block of commands which are grouped because for example together they offer a related set of functions:

#d_index_title Title text

This labels the start of a header in the HTML documentation which contains the text supplied after the tag. This also creates a link from the index file to this header.

If this is the first #d_index_title in a file then it is usual to add the name of the file in parentheses at the end of the text.

#d_intro_title Title text

This labels the start of a header in the HTML documentation which contains the text supplied after the tag. This also creates a link from the index file to this header.

#d_intro Text ...

Used for explanatory text (e.g. an overview of a group of commands) which is written into the HTML documentation.

Multiple #d_intro tags can be used - each tag creates a new paragraph in the HTML document.

Examples

The following is an example of documenting a simple command:

#-----------------------------------------------------------------------
proc AddNumbers { x y args } {
#-----------------------------------------------------------------------
#d_sum Adds together two numbers
#d_desc This command adds together two numbers and returns their sum.
#d_desc The result is unreliable if either of the arguments is not \
a valid integer or float.
#d_arg x First number to be added
#d_arg y Second number to be added
#d_opt0 -subtract
#d_opt1 Subtract the second number from the first (instead of adding)
  set operation "+"
  if { [lsearch -exact $args "-subtract"] > -1 } {
    set operation "-"
  } 
  return [expr $x $operation $y]
}

Using these doc comments, create_docs would generate something which looked like:

The following is an example of documenting a group of commands:

#d_index_title Maths Functions and Utilities (utils/maths.tcl)
#d_intro_title Maths Functions

#d_intro These are a set of commands for performing useful mathematical \
operations.
#d_intro They act as wrappers for the Tcl expr command.

In the HTML index file this would create a link to the documentation for this file which would include:

Usage of the create_docs script

The create_docs script is located in the $CCP4/bin directory, and generates HTML documentation from the doc comments and procedure definitions which it finds in the Tcl source code.

create_docs can be run without any arguments, in which case it will by default look for Tcl source code files in subdirectories of the directory $CCP4I_TOP, writing HTML documentation in the directory $CCP4I_TOP/help/programmers/progdocs with an index file named index.html.

These settings can be over-ridden by specifying them on the command line:

create_docs [ srcPath [ docPath [ indexfile ] ] ]

where the arguments have the following meanings:

• srcPath: where to look for the Tcl source code
• docPath: where to write for the HTML documents
• indexfile: the name to use for the index file

The names of the subdirectories and the source code files (as well as the names of the output HTML files) are hard-coded within the script. This means that any new source code files will have to be added to the create_docs script manually in order to extract the documentation in this way.