104.texi

\input texinfo          @c -*-texinfo-*-
@c %**start of header
@setfilename class-doc
@settitle Class Documentation Standards
@c %**end of header

@c $Source$
@c $Revision$
@c $Date$
@c $Author$
@c $State$

@c $Log$
@c Revision 19.0  2003/07/16 03:48:48  aips2adm
@c exhale: Base release 19.000.00
@c
@c Revision 18.0  2002/06/07 19:56:55  aips2adm
@c exhale: Base release 18.000.00
@c
@c Revision 17.0  2001/11/12 18:37:33  aips2adm
@c exhale: Base release 17.000.00
@c
@c Revision 16.0  2001/05/02 23:26:25  aips2adm
@c exhale: Base release 16.000.00
@c
@c Revision 15.0  2000/10/26 14:25:53  aips2adm
@c exhale: Base release 15.000.00
@c
@c Revision 14.0  2000/03/23 14:40:45  aips2adm
@c exhale: Base release 14.000.00
@c
@c Revision 13.0  1999/08/10 17:15:04  aips2adm
@c exhale: Base release 13.000.00
@c
@c Revision 12.0  1999/07/14 22:01:15  aips2adm
@c exhale: Base release 12.000.00
@c
@c Revision 11.0  1998/10/03 04:52:24  aips2adm
@c exhale: Base release 11.000.00
@c
@c Revision 10.0  1998/07/20 15:33:59  aips2adm
@c exhale: Base release 10.000.00
@c
@c Revision 9.0  1997/08/25 18:51:09  aips2adm
@c exhale: Base release 09.000.00
@c
@c Revision 8.0  1997/02/20 01:21:17  aips2adm
@c exhale: Base release 08.000.00
@c
@c Revision 7.0  1996/06/24 08:16:46  aips2adm
@c exhale: Base release 07.000.00
@c
@c Revision 6.0  1996/01/24 01:10:14  aips2adm
@c exhale: Base release 06.000.00
@c
@c Revision 5.0  1995/07/26 07:03:13  aips2adm
@c exhale: Base release 05.000.00
@c
# Revision 4.0  1994/08/26  05:07:17  aips2adm
# exhale: Base release 04.000.00
#
# Revision 3.0  1993/11/01  04:20:54  aips2mgr
# exhale: Base release 03.000.00
#
# Revision 2.0  1993/03/16  08:17:14  aips2mgr
# exhale: Base release 02.000.00
#
# Revision 1.1  1992/04/09  19:53:50  bglenden
# Initial revision
#
@c Revision 1.1  1992/01/30  15:44:53  cflatter
@c Initial revision
@c

@ifinfo
This file documents the AIPS++ project standards for documenting
C++ classes in header files.
@end ifinfo

@titlepage
@title Class Documentation Standards
@subtitle for the AIPS++ Project
@subtitle (Pre-release Version)
@author Chris Flatters

@page

@vskip 0pt plus 1filll
@center{This page deliberately not left blank.}
@vskip 0pt plus 1filll

@node Top, Basic Principles, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top Class Documentation Standards

This document contains standards and recommendations for writing
reference documentation for AIPS++ classes.  The authoritative
documentation for a class is assumed to be a commented C++ header
file.  The standards set out in this document support the use of
automated tools which can extract the documentation from the
header file and transform it to a form suitable for a typesetting
program such as @TeX{}.

These standards comprise mandatory @dfn{requirements} and advisory
@dfn{recommendations}.  Requirements and recommendations are written as
follows.

@table @strong
@item Requirement:
you must do this.

@item Recommendation:
it is advisable to this.
@end table

This pre-release edition is being distributed to solicit comments.
Please send any comments to @code{cflatter@@nrao.edu}.

@ifinfo
The first part of this master menu lists the major nodes in this Info
document including the indices.  The rest of the menu lists all of the
lower-level nodes in the document.
@end ifinfo

@menu
* Basic Principles::            Basic Principles
* Header File Layout::          Header File Layout
* An Example Header File::      An Example Header File
* Index::                       Index

 --- The Detailed Node Listing ---

Basic Principles

* Contractual Obligations::     Contractual Obligations
* Writing Mathematics::         Writing Mathematics
* Comment Delimiters::          Comment Delimiters

Header File Layout

* Class Definition Layout::     Class Definition Layout

Class Definition Layout

* Constant Definitions::        Constant Definitions
* Enum Type Definitions::       Enum Type Definitions
* Function Declarations::       Function Declarations
@end menu

@node Basic Principles, Header File Layout, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Basic Principles

Class documentation should provide programmers with all of the detailed
information they need in order to be able to use instances of a given
class.  It should never be necessary for a programmer to refer to the
actual implementation of an object; examining implementation code is a
tedious and error prone business.  If this is to be avoided then the
class documentation must be accurate, precise and (most importantly)
complete as well as comprehensible.

A C++ class declaration contains a great deal of information about a
class that is guaranteed to be reliable.  For example, it lists the
names of the member functions, their arguments and any exceptions that
they may raise@footnote{Current versions of C++ do not support
exceptions}.  The C++ code alone does not, however supply complete
information about a class and must be supplemented by a commentary.

@menu
* Contractual Obligations::     Contractual Obligations
* Writing Mathematics::         Writing Mathematics
* Comment Delimiters::          Comment Delimiters
@end menu

@node Contractual Obligations, Writing Mathematics, Basic Principles, Basic Principles
@comment  node-name,  next,  previous,  up
@section Contractual Obligations

@cindex{Programming by contract}
@cindex{Contract}
@cindex{Contractual obligations}
Programming by contract is a common paradigm in object-oriented
programming.  The behaviour of any class can be defined by a set
of contracts between the class and its clients that take this form.

@quotation
I have a member function called @var{X} taking formal arguments @var{Y}
and returning @var{Z}.  If you ensure that condition @var{P} is true and
then call member function @var{X} then I guarantee to do @var{Q}.
@end quotation

The class documentation should be a statement of the relevant contracts:
it should say exactly what the class guarantees to do and what the
obligations of the class' clients are.  There should be no
loopholes.

@cindex{Class invariant}
@cindex{Precondition}
@cindex{Postcondition}
Class invariants, preconditions and postconditions are useful in
documenting contractual obligations.  A class invariant is a condition
that must hold for all objects of a given class, a postcondition is a
condition that will hold after a function is executed (representing a
responsibility of the class) and a precondition is a condition that must
hold before a function is called (representing an obligation on the
client).  All three are mathematical in nature and are best written in
mathematical notation.  Unfortunately, many AIPS++ programmers are not
comfortable with the mathematics required.  This leads to the first
recommendation.

@table @strong
@item Recommendation:
you should use class invariants, preconditions and postconditions and
write them using mathematical notation if you are comfortable with these
concepts.
@end table

However, if these concepts are used, we can not guarantee that all AIPS++
programmers will understand them. 

@table @strong
@item Recommendation:
if you document a class using mathematical conditions that are not
immediately obvious to a reader with a working knwoledge of C++ then
you should either describe the same conditions informally in plain
English or provide them with a descriptive label.
@end table

An example of a mathematical condition with a descriptive label follows.

@example
@cartouche
all array elements are zero:
    forall( int i; 0 <= i && i < current.length(); current[i] = 0 )
@end cartouche
@end example

@node Writing Mathematics, Comment Delimiters, Contractual Obligations, Basic Principles
@comment  node-name,  next,  previous,  up
@section Writing Mathematics

If mathematical notation is used it must be written in a form that can
be easily read and understood in a header file.  This rules out the
use of mathematical mark-up languages such a @TeX{}.  A programmer
may assume, however, that the readers of his documentation understand
C++ notation.

@table @strong
@item Recommendation:
write mathematical conditions in a form that is as close to C++ as
possible.
@end table

C++ notation is rather too limited to be useful on its own and some
conventions must be adopted to extend it for documentation purposes.
The following notations are recommended.

@table @code
@item result
@cindex{Return value}
@cindex{Function return value}
Use the pseudovariable @code{result} to represent the return value
of a function.

@item current
@cindex{Current object}
@cindex{*this}
Use the name @code{current} to refer to the current object;
@code{current} is less clumsy than the @code{*this} notation that must
be used in actual C++ code.

@item forall
@cindex{forall}
@cindex{Universal quantification}
Write universal quentifications using the template @code{forall(
@var{declarations}; @var{restrictions}; @var{condition} )}.

@item exists
@cindex{exists}
@cindex{Existential quantification}
Write existential quantifications using the template
@code{exists( @var{declarations}; @var{restrictions}; @var{condition} )}

@end table

@node Comment Delimiters,  , Writing Mathematics, Basic Principles
@comment  node-name,  next,  previous,  up
@section Comment Delimiters

@cindex{Comment delimiters}
Comments that contain documentation must be written in a form that can
be easily recognized and extracted by a mechanical processor.  All
documentation comments have the following form.

@example
@cartouche
/*@var{X}*
 *
 * @var{Some text}
 *
 *@var{X}*/
@end cartouche
@end example

@var{X} is a single letter code that is used to denote what is being
documented in the comment.  Valid codes are

@table @code
@item H
file headers

@item C
class headers

@item F
function headers

@item T
constants

@item E
named and unnamed enumerations

@end table

A documentation extraction program uses the @code{/*@var{X}*} and
@code{*@var{X}*/} delimiters to recognize comments that should be
extracted.  Comments that are delimited by plain @code{/*} and @code{*/}
are discarded as are comments that begin with @code{//}.  The leading
column of asterisks makes it easy for a human reader to distinguish text
in the comment from C++ code.

@node Header File Layout, An Example Header File, Basic Principles, Top
@comment  node-name,  next,  previous,  up
@chapter Header File Layout

A header file contains the definition of one or more C++ classes.

@table @strong
@item Requirement:
header files must conform to the template shown below.
@end table

@example
@cartouche
/*H* -*- C++ -*-
 *
 * @var{header file description}
 *
 * @var{copyright statement}
 *
 *H*/

#ifndef @var{identifier}
#define @var{identifier}

@var{class definition list}

@var{inline functions}

#endif
@end cartouche
@end example

GNU emacs uses the @code{-*- C++ -*-} string to distinguish files
containing C++ code from those containing C code.  

@cindex{Header file description}
@cindex{Copyright statement}
The @var{header file description} should say what publicly available
classes are defined in the file and briefly describe how they are
related to one another.  The form of the @var{copyright statement} has
yet to be decided at the time of writing.

@cindex{Class definition list}
The @var{class definition list} is a list of class definitions.
Definitions of all @var{inline functions} must follow the last class
definition and will be ignored by documentation extraction tools.

@menu
* Class Definition Layout::     Class Definition Layout
@end menu

@node Class Definition Layout,  , Header File Layout, Header File Layout
@comment  node-name,  next,  previous,  up
@section Class Definition Layout

@table @strong
@item Requirement:
class definitions must conform to the template shown below.
@end table

@example
@cartouche
/*C*
 *
 * @var{class description}
 *
 * INVARIANTS
 *
 * @var{label}: @var{condition}
 * @var{label}: @var{condition}
 *
 *C*/
class @var{name} : @var{ancestors}
@var{friend class declarations}
@{
public:
    @var{constant definitions}
    @var{enum type definitions}
    @var{function declarations}
protected:
    @var{constant definitions}
    @var{enum type definitions}
    @var{function declarations}
private:
    @var{constant definitions}
    @var{enum type definitions}
    @var{function declarations}
@};
@end cartouche
@end example

@table @strong
@item Recommendation:
put the @code{public}, @code{protected} and @code{private} parts of a
class definition in that order so that a human reader can find those
parts of the class definition that are most relevant to him near the top
of the definition.
@end table

@cindex{Class description}
The @var{class description} should be an informal description of the
class in plain English.  It should state what the class represents and
give a good idea of the responsibilities of the class.  If the class
has particular memory requirements then they should be described here.

@cindex{Label}
@cindex{Condition}
The @code{INVARIANTS} section is optional.  Each @var{label} should be
a short phrase describing the invariant condition and the
@var{condition} should be a mathematical description of the same
condition (@pxref{Writing Mathematics}).  The label may be omitted
if the meaning of the @var{condition} is self-evident or both the
@var{label} and @var{condition} may be replaced by an English phrase if
the condition can not easily be written in mathematical form.

@menu
* Constant Definitions::        Constant Definitions
* Enum Type Definitions::       Enum Type Definitions
* Function Declarations::       Function Declarations
@end menu

@node Constant Definitions, Enum Type Definitions, Class Definition Layout, Class Definition Layout
@comment  node-name,  next,  previous,  up
@subsection Constant Definitions

A class may define one or more constants.

@table @strong
@item Requirement
constant definitions should conform to the following template.
@end table

@example
@cartouche
/*T*
 *
 * @var{constant description}
 *
 *T*/
@var{C++ constant definition}
@end cartouche
@end example

@cindex{Constant description}
The @var{constant description} should state what the constant represents
and, if the value of the constant does not appear in the C++ definition
(ie. if the constant is a @code{static} class member), then the value
of the constant should be included in the description as in the
following example.

@example
@cartouche
/*T*
 *
 * The mathematical constant pi (3.14159265358978).
 *
 *T*/
 static const double pi;
@end cartouche
@end example

@node Enum Type Definitions, Function Declarations, Constant Definitions, Class Definition Layout
@comment  node-name,  next,  previous,  up
@subsection Enum Type Definitions

Classes often define @code{enum} types to represent such things as
states.

@table @strong
@item Requirement:
Definitions of enumerated types must conform to the following template.
@end table

@example
@cartouche
/*E*
 *
 * @var{enum type description}
 *
 *E*/
@var{C++ enum type declaration}
@end cartouche
@end example

@cindex{enum type description}
The @var{enum type description} should state, in plain English, what
the enumerated type represents. It should also list the symbolic values
of the enumeration and what they represent as in the following example.

@example
@cartouche
/*E*
 *
 * This enumeration represents the possible status returns from a
 * Stack operation.
 *
 *    ok            operation successful
 *    overflow      stack would have overflowed: stack unchanged
 *    underflow     stack would have underflowed: stack unchanged
 *    
 *E*/
enum stackState @{ok, overflow, underflow@};
@end cartouche
@end example

@node Function Declarations,  , Enum Type Definitions, Class Definition Layout
@comment  node-name,  next,  previous,  up
@subsection Function Declarations

Member functions and friend functions require extensive documentation.

@table @strong
@item Requirement:
Function declarations must conform to the following template.

@example
@cartouche
/*F*
 *
 * @var{function description}
 *
 * PRECONDITIONS
 *
 * @var{label}: @var{condition}
 *
 * POSTCONDITIONS
 *
 * @var{label}: @var{condition}
 *
 *F*/
@var{C++ function declaration}
@end cartouche
@end example

@cindex{Function description}
The @var{function description} should describe what the function does,
what conditions it will work under, what it returns and what its
arguments are.  The option @code{PRECONDITIONS} and
@code{POSTCONDITIONS} clauses repeat parts of this description in a
more precise mathematical form.  They may be written as a mathematical
statement with an optional label (@pxref{Writing Mathematics}) or in
plain English. Here is an example of a function declaration@footnote{The
@code{true} precondition indicates that the behaviour of
@code{Stack::pop()} is defined under all circumstances}.

@example
@cartouche
/*F*
 * 
 * Pop an item from the stack.  If the operation is completed
 * successfully then the value returned is ok. If the stack is
 * already empty the the value returned is underflow.
 *
 * PRECONDITIONS
 *    true
 *
 * POSTCONDITIONS
 *    (!current.empty() && result == ok)
 *    || (current.empty() && result == underflow)
 *
 *F*/
stackState pop();
@end cartouche
@end example

@node An Example Header File, Index, Header File Layout, Top
@comment  node-name,  next,  previous,  up
@chapter An Example Header File

@example
/*H* -*- C++ -*-
 *
 * This file contains the definitions for the Stack class.
 *
 * << Copyright statement belongs here >>
 *
 *H*/

/*C*
 *
 * The BoundedStack class represents a Stack (LIFO) of an arbitrary
 * type and of fixed size.  The number of entries that can be placed
 * on a Stack is given as a template argument when the Stack is
 * instantiated.
 *
 * Objects of type T may be pushed onto or popped from the top of
 * the Stack using push() and pop().  The topmost element on the
 * Stack may be examined using top().  A program can test whether
 * a Stack is empty of full using empty() or full().
 *
 *C*/

#ifndef STACK_H
#define STACK_H

class Stack<class T, int size>
@{
public:

    /*F*
     *
     * The default constructor.
     *
     * PRECONDITIONS
     *     true
     *
     * POSTCONDITIONS
     *    stack is empty: current.empty()
     *
     *F*/
    Stack();

    /*F*
     *
     * Return true (a non-zero integer) if the Stack is empty or
     * false (zero) if the Stack is not empty.
     *
     *F*/
    int empty() const;

    /*F*
     *
     * Return true (a non-zero integer) if the Stack is full or
     * false (zero) if the Stack is not full.
     *
     *F*/
    int full() const;

    /*F*
     *
     * Return the value of the item at the top of the Stack.  The
     * The value returned is the same as the last value pushed onto
     * the stack.  The Stack may not be empty.
     *
     * PRECONDITIONS
     *     stack not empty: !current.empty()
     *
     *F*/
    T top() const;

    /*F*
     *
     * Push the value ton to the Stack.  The Stack must not be
     * full when this function is called.
     *
     * PRECONDITIONS
     *     stack not full: !current.full()
     *
     *F*/
    void push(T t);

    /*F*
     *
     * Remove (pop) the topmost value from the Stack.  The Stack
     * must not be empty when this function is called.
     *
     * PRECONDITION
     *     stack not full: !current.full()
     *
     *F*/
     void pop();

private:
     T implementation[size];    // Array of values
     int max_size;              // Max. number of values on stack
     int cur_size;              // Current number of values on stack

@};

#endif
 
@end example


@node Index,  , An Example Header File, Top
@comment  node-name,  next,  previous,  up
@unnumbered Index

@printindex cp

@contents
@bye