CheckMate 3_6 Programmers Guide
December 08, 2003
How to Use This Document
This document is generated by the tool mdoc from a collection
of MATLAB m-files to provide general information such as syntax and input/output
description for each individual function in m-file collection as well as
the information about the call structure among the functions and the graphical
user interface (GUI) events associated with these functions. The user
can use the function index and event index to navigate the document. We
briefly describe the naming convention and the structure of the information
provided in this document below.
Naming Convention
Directory
The symbol ~ is used to denote the root directory for the current
collection of m-files. This is because the m-files may be installed at
different root directories on different machine. We assume, however, that
the directory structure for the m-files is preserved.
Function Identifier
A function in this document is referred to using the following convention.
1. [function_name]
This is used when the function is the main function or script in an
m-file with the same name. This is also used for a local function when
the name is marked (local) or (self).
2. [file_name]::[function_name]
This is used when the function is a local function (not the main function)
inside the an m-file.
3. [class_name]/[function_name]
This is used when the function is a method of a class in an m-file with
the same name.
4. [class_name]/[file_name]::[function_name]
This is used when the function is a local function (not the main function)
inside the a method m-file.
5. [function_name]*
This is used when the function is polymorphic. Polymorphic functions
include all methods other than the class constructors and other functions
which share the same names as these methods.
Disclaimer: Note that mdoc simply uses the polymorphic
identifier to make the user aware of the potential polymorphism and does
not try to rigorously resolve the method calls within the source code,
as it is often the case that the actual calls can only be determined at
run-time.
Special Comment Tags
The following tags may be placed in comments in various points throughout
the source code aid the document generation tool in gathering special information.
1. <CALL LINE=[offset]> [function_name]
This tag is used to indicate a function call that may not be obvious
to the reader, e.g. when the programmer uses an eval statement
to make a function call. The document generator may also fail to detect
the call in such situation. The [offset] parameter indicates the
line number where the call happens relative to the current line number.
The [function_name] parameter indicates the callee function name,
which follows the naming convention described above. All parameters must
be specified within a single line for this tag.
2. <EVENT GROUP="[group_name]" LINE=[offset]> [event_name]
This tag is used to associate a line of code with a GUI event. The parameter
[group_name]
and [event_name] indicate the event group and event name, respectively
(see the Event Information section below). The [offset]
parameter indicates the line number in the source code associated with
the event relative to the current line number. All parameters must be specified
within a single line for this tag.
4. <NOTE> [comments]
This tag may follow a <CALL> or an <EVENT> tag.
It is used to provide the document generator with additional information
associated with the immediately preceding event or call tag. The [comments]
parameter
is any description that the programmer wishes to associated with the preceding
call or event. The description may span multiple lines of contiguous comments.
3. <NOCALL LINE=[offset]>
This tag tells the document generator to ignore all function calls in
the specified line number. The [offset] parameter is the line
number in the source code relative to the current line number. The offset
value, however, must be positive, i.e. the tag must precedes the line for
which the calls are to be canceled. All parameters must be specified within
a single line for this tag.
Function Information
For each function, the following information is provided.
General Help Information
This is the information obtained from the help comment for each function,
i.e. the contiguous comment lines immediately following the function header
line. Typically, the information pertains to the syntax, function description,
function input/output specifications, etc.
Callers
A list of functions that call the current function.
Callees
A list of functions that the current function calls. For each callee function,
the line numbers where the callee is called in the parent m-file of the
current function are provided along with the description of the function
call in each line, if available.
Call Tree
A tree representing the function call structure starting from the current
function. Each node in the tree corresponds to a function. The call tree
may repeat when the same function is called at various depths in the call
tree. When such repetition occurs, the repeated node is marked with the
word (repeat) at the end.
Disclaimer: The call tree generated by mdoc only represents
possible
calling sequences originating from the current function. A specific call
path may or may not be possible depending on the run-time conditions.
Event Information
An event that triggers the execution of a MATLAB function occurs when the
user interacts with a graphical user interface (GUI) object or types a
command at the MATLAB command prompt. Events in this document are organized
into groups, each typically corresponds to a GUI window. Each event
has a unique name within the group. For each event, the following information
is provided.
Group
The group which the current event belongs to.
Name
The name of the current event, displayed at the beginning of the documentation
for the event.
Description
A list of locations in the source code in various m-files that pertain
to the event. For each location, a brief description indicating the relevance
of the code with respect to the event is given. The description may indicate
that the particular piece of code defines the callback function for the
event or that the code is the actual entry execution point when the event
occurs.
Disclaimer
The tool mdoc is written by Alongkrit Chutinan, Emmeskay Inc.
and comes absolutely without any warranty.