------------------------------------------------------------------------------- Program Purpose ------------------------------------------------------------------------------- class2info Parses a C++ header file and produces a file which contains infor mation about the class in the header file, in a form which is more easily parsed by other tools. info2man Takes the output file from class2info and produces a UNIX style manual page for each class described in the input file. class2man Combines the programs class2info and info2man, to pro duce a UNIX style manual page for each class declaration in a header file. info2mml Takes the output file from class2info and produces a Frame mml file for each class described in the inout file. class2mml Combines the programs class2info and info2mml, to pro duce a Frame mml file for each class declaration in a header file. -------------------------------------------------------------------------------Using the same front end parser as the documentation extraction tools, are the following tools:
---------------------------------------------------------------------------- Program Purpose ---------------------------------------------------------------------------- info2src Takes the output file from class2info and produces on stan dard output, empty stub functions for each of the member func tions listed in the class declarations described in the file. class2src Combines the programs class2info and info2src, to pro duce on standard output, empty stub functions for each of the member functions listed in the class declarations described in a header file. ----------------------------------------------------------------------------These use information contained in a C++ class header file, to produce code stubs suitable for the corresponding implementation file for that class.
The format which C++ class header files must adhere to is the subject of the remainder of this document.
// = SECTION TITLEAny text following the title of the section, up till the end of the comment, the start of another section, or a line commencing with `==', is interpreted to be the body text for that section. Multiple sections may be documented in a single comment block. Any leading, or trailing blank lines will be discarded in the output. An example of a comment block containing multiple sections is given below.
// Body text.
// =====================================================Certain sections, appearing at global scope, are given special treatment in the generated manual pages. These are:
//
// = SECTION TITLE1
// Body text.
//
// = SECTION TITLE2
// Body text.
//
// =====================================================
------------------------------------------------------------------------------- Section Description ------------------------------------------------------------------------------- LIBRARY The name of the library, of which the file is a part. This will appear in the header of each manual page. FILENAME The name of the file. This will be used in conjunction with the library name, to produce an include line in the synopsis. AUTHOR(S) The names of the authors. If the authors are placed on sepa rate lines, commas should not be used to terminate each line. If more than one author is placed on a single line, a comma should be used to separate each. COPYRIGHT The copyright applying to the contents of the file. VERSION The version number of the file. If using RCS, this would be set to `$Revision$'. DATE RELEASED The date that the current version of the file was released. If using RCS, this would be set to `$Date$'. RCSID The raw ID produced by RCS. Normally set to `$Id$'. SCCSID The raw ID produced by SCCS. Normally set to `%W%'. -------------------------------------------------------------------------------Using these tags, you can construct a comment block at the start of each file, which describes the file, authors and version of the file. For example:
/*
// ========================================================
//
// = LIBRARY
// OTC
//
// = FILENAME
// collctn/list.hh
//
// = RCSID
// $Id$
//
// = AUTHOR(S)
// Graham Dumpleton
//
// = COPYRIGHT
// Copyright 1991 1992 1993 OTC LIMITED
//
// =====================================================
*/
// = EXAMPLEit will appear as:
// void dump(Class* theClass)
// {
// cout << theClass->name() << endl;
// }
void dump(Class* theClass) { cout << *theClass << endl; }If the example is complicated, the result will be unreadable.
To let the documentation tools know that the text you have included is special and should not be reformatted, you can mark it as being a code example. For example:
// = EXAMPLEThe commands in this example are, `BEGIN<CODE>'and `END<CODE>'. In all cases, the format of commands used to change the formatting of a block of text is:
// = BEGIN<CODE>
// void dump(Class* theClass)
// {
// cout << *theClass << endl;
// }
// = END<CODE>
// = BEGIN<COMMAND>The `BEGIN' for a command, must always have a matching `END'. The commands which are currently understood by the documentation tools are:
// ....
// = END<COMMAND>
-------------------------------------------------------------------- Command Description -------------------------------------------------------------------- INDENT Text will be indented with respect to the surrounding text. NOFILL Text will be output with indentation and formatting as it appears. CODE Text is output in `NOFILL' mode using a fixed width font. COMMENT Text will not be output. This command would be used to sur round comments about the implementation, which should not appear in the user documentation. --------------------------------------------------------------------Commands may be nested, with the exception that no commands should be nested within a `CODE' block.
---------------------------------------------------------------------------------- Command Description ---------------------------------------------------------------------------------- <text> Text between `<` and `>', is displayed in a fixed with font. <{text}> Text between `<{` and `}>', is displayed in an italic font. <[text]> Text between `<[` and `]>', is displayed in a bold font. ----------------------------------------------------------------------------------`<text>' should be used for all C++ keywords, function names, variable names, class names, expressions etc. The others can be used to highlight text. An example of how inline formatting commands may be used, follows:
// = ASSERTIONSSince `<`, and `>' are special characters, you must prefix them with a `\' if the actual character needs to printed. For example:
// Assertion checks can be placed into code using
// the <OTCLIB_ASSERT()> macro. Note that you should
// <[NOT]> use an expression in the condition check,
// which has a side effect, the result of which is
// necessary for the correct operation of the
// program. The reason for this, is that assertions
// can be compiled out of your code by defining the
// <NDEBUG> symbol.
<operator\<()>If `{`, `}', `[` or `]' appear adjacent to either `<` or `>' in the forms described above, they will also need to be prefixed with a `\'. For example:
<\[A-Za-z_]*>
template<class T>These sections will only appear in the manual page for that class. Sections appearing with a class, which are given special treatment in the manual page are:
class OTC_List : public OTC_Collection<T>
// = SECTION NAME
// Body text.
{
...
};
----------------------------------------------------------------------------- Section Description ----------------------------------------------------------------------------- TITLE A one line description of the class. This will be used in the `NAME' section of the manual page. CLASS TYPE The type of class. For example: Abstract or Concrete. AUDIENCE Who may use the class. For example, the class may only be of interest to the class librarian. DESCRIPTION A description of the class. NOTES Any special features, unimplemented but desirable features, side effects, or known bugs. SEE ALSO References to any associated documents, systems or classes. If listed separately on each line, no comma should be used at the end of the line. If more than one appears on a single line, a comma should be used to separate them. EXAMPLE If realistic, a brief example of how the class may be used. Copious examples should not be included here, but should be described in a separate user guide. -----------------------------------------------------------------------------
void func1(); // Commentor on the line immediately following the declaration.
void func2(); // Comment
void func1();The comment may extend over more than one line. A comment for a particular member variable or function will be terminated by any line which doesn't contain only a comment. A comment will only be associated with the declaration which immediately preceeds it. For example:
// Comment
void func2();
// Comment
void func1();the comment is associated with func2() only and not func1().
void func2();
// Comment
If a member function is defined inline, the comment must be placed after the code. For example:
void func1() { ... }A limitation of the extraction tools, currently requires that you do not place comments, or blank lines, within the body of the inline code.
// Comment
void func2()
{ ... }
// Comment
makes it easier to find a function which serves the purpose you require.
A contract is a grouping of operations which fulfill a responsibility of the class. Contracts could include:
If contract sections are used, only functions which appear under a contract section will appear in the manual page. Functions which are not in a contract section are not displayed. If no contract sections are used, two default contract sections, with labels `PROTECTED MEMBERS' and `PUBLIC MEMBERS', will be created.
An example of a class using contracts is:
class Class
// ...
{
public:
~Class();
// This will not appear in the
// manual page.
// = INITIALISATION
Class(char const* theString);
// This will appear in the manual
// page in section INITIALISATION.
//
// Inline formatting, for example:
// <theString>, may be used, as may
// block formatting commands.
// = QUERY
// As with all other sections, a contract
// section can have body text. This will appear
// in the manual page after the section name and
// before the functions are listed.
char const* string();
// Extra information for the current contract may
// also be included between members. This is
// generally used where it is necessary to make a
// comment about a specific set of members in a
// contract.
OTC_Boolean isValid() const;
};