Tools: MacApp

Audience

An engineer writing or modifying code in the MacApp framework.

In order to simplify the maintenance of the MacApp documentation, specifically the Class and Method Reference (C&MR) the MacApp team will be embedding the source for the documentation of the Class and Method Reference right into the source code of MacApp.

Our approach is intended to facilitate making the documentation track changes in the code better. In this way each software engineer could make small changes to existing class and method reference (C&MR) descriptions or write preliminary material for new material. In any case, the resulting descriptive material will be reviewed and edited by a writer and changed directly within the source code as required.

Documentation Guidelines

There are 7 kinds of items which can be described in the MacApp Class & Method Reference:

• Source Files
• Classes
• Class Data Members
• Class Functions
• Global Functions
• Function Parameters
• Optional Items

All of these can be codified in the source code of the MacApp product. Additional types of descriptions may be added at a later time.

In addition to item descriptions there will also be general information that cannot conveniently be codified directly in the source files.

Why Standards?

Automated scripts are used for parsing the source code and generating a database of key field types along with their descriptions and other identifying information. From this database a QuickView or HTML file can be generated using a script. Following these standards prevents script-busting problems from occuring.

Codification Standards

A primary goal in embedding the C&MR material directly in the source code files is to avoid annoying tagging and distracting content. Carefully following the guidelines will allow us to meet this goal.

Comment Types

The documentation content which goes into the C&MR is contained in the source code as comments.

Each line is commented using the '//' C++ notation. The C-style comments using '/*' and '*/' are not to be used because they are too difficult to parse properly.

Lines consisting of all dashes ('//-------------...--------------') are ignored at the beginning and end of a comment section and they can be used to separate the function implementation comments from the parameter descriptions and notes.

General Paragraph Structure

Any descriptions can consist of multiple lines and paragraphs. Lines are collected into a paragraph until a line ending with a period (with optional trailing whitespace) is detected. The next line begins the next paragraph. Comments for the item are collected into paragraphs until the next section is detected.

File Descriptions

A description of a source code file will be encoded immediately after the copyright block.

[This needs to be completed.]

Class Description Specifications

Class Definitions

The description of a class is contained in a comment immediately following the class specification and immediately before the opening brace of the class definition; it may not start on the same line as the class specification. The description stops at the opening brace of the the class specification. The description should always contain the name of the class within the first few words of its text.

class TTextGridView : public TGridView
//-----------------------------------------------------------------------------------
// TTextGridView: A sub-class of TGridView that can handle the display of
// text in its cells.
//-----------------------------------------------------------------------------------
{
  MA_DECLARE_CLASS;
         

Class Data Members

Data member descriptions can start on the same line as the data member or the following line and span several lines. The description stops at the beginning of the next line which does not start with a comment.

    CTextStyle fTextStyle;       // The font, font size, style, and color of the text.
 
    short fTextStyleRsrcID;      // Rsrc ID of 'TxSt' resource which has
                                 // TextStyle information.

Class Function Definitions

Function definitions consist of a brief function description, a complete function description, parameter definitions, and optional sections which give supplementary notes such as 'Call' and 'Override'.

Function Abstract

A brief function abstract is coded within the header file immediately after each function declaration. It should be no more than a single line although this is not a requirement. The description stops at the beginning of the next line which does not start with a comment.

    virtual void DrawCell(const GridCell& aCell, const VRect& aRect);
                   // Draws the text contained in a TGridView cell.

Note that inline function declarations will not be scanned for an abstract, rather, they will be scanned for a complete function description.

Complete Function Description

The complete function description is usually coded within the implementation file immediately after the function prototype but before the opening brace of the function. It precedes the Parameter Definitions and Optional Sections. The function name should always included within the first few words of the descriptive text. Complete function descriptions may also be coded within the header file when the function is inlined.

For constructors, the complete function description must follow the initialization block, if present, the description being placed immediately before the opening brace of the function.

See the example below.

Return Value Description

The description of the function's return value is usually coded within the implementation file immediately after the Complete Function Description separated by a blank comment line. The keyword 'Returns' is given first and is terminated with a colon (:). The description of the return value can span multiple lines and paragraphs. Whitespace between the colon and the descriptive text is ignored.

A return value description is optional and should not be provided in cases where the function has a 'void' return type.

Parameter Description

The description of each parameter in a function should be coded within the implementation file immediately after the optional Return Value Description or, if there is no Return Value Description, right after the Complete Function Description separated by a blank comment line. The parameter name is given first and is terminated with a colon (:). The description of the parameter can span multiple lines and paragraphs. Whitespace between the colon and the descriptive text is ignored.

Notes

The Notes sections is normally composed of the 'Call?' and 'Override?' notes though it can be used for other special sections such as 'Note!' or 'Caution!'. The Notes sections is coded within the implementation file normally right after the Parameter Descriptions from which it may be separated by an optional blank comment line. Each optional section consists of a keyword, such as 'Call' or 'Override' that is then followed by a question mark or exclamation mark. Whitespace between the question mark or exclamation mark and the descriptive text is ignored.

Note: while it is possible to intermix the return value description, parameter descriptions and notes we highly recommend, for readability, that the return value description be listed first, followed by the parameter descriptions, and finally the notes.

Global Data

The description of a global variable can start on the same line as the data member or the following line and can span several lines. The description stops at the beginning of the next line which does not start with a comment.

Enums

Enum descriptions can start on the same line as the enum or the following line and can span several lines. The description stops at the beginning of the next line which does not start with a comment.

Typedefs

Descriptive comments about typedefs are not collected at present.

Defines

Descriptive comments about defines are not collected at present.

Example

In the header file we might have:

class TTextGridView : public TGridView
//-----------------------------------------------------------------------------------
// TTextGridView: A sub-class of TGridView that can handle the display of
// text in its cells.
//-----------------------------------------------------------------------------------
{
  MA_DECLARE_CLASS;
	
public:
[Snip]
  
//------------------------------------------------------------------------------------
// General Methods
//------------------------------------------------------------------------------------
 
    virtual void DrawCell(const GridCell& aCell, const VRect& aRect);
                   // Draws the text contained in a TGridView cell.
 
    virtual bool Focus();
                   // Set up the drawing environment for the view.
 
    virtual void DoFulfillPromise(TDragItem* promisedItem);
                   // Fill the promisedItem with the actual data that was promised.
 
protected:
    CTextStyle fTextStyle;       // The font, font size, style, and color of the text.
 
    short fTextStyleRsrcID;      // Rsrc ID of 'TxSt' resource which has
                                 // TextStyle information.
 
    short fJustification;        // The justification style for the text in the 
                                 // cells. See teFlushDefault for a list of
                                 // valid values.
 
    short fLineHeight;           // The height of each item, including leading.
 
    short fLineAscent;           // The position of the text's baseline relative to
                                 // the top of the line.
 
    Boolean fPreferOutline;      // True if TrueType outline fonts should be used
                                 // when available.
};

In the implementation file we might have:

void TTextGridView::DrawCell(const GridCell& aCell, const VRect& aRect)
// DrawCell draws the text contained in a TGridView cell.
// MacApp uses this method as part of the process of drawing TTextGridView objects.
//
// aCell: Specifies the cell whose text is to be drawn.
// aRect: Defines the rectangle, described in view coordinates, in which MacApp
//        draws the text. 
//
// Call?     Seldom.
// Override? As needed.  If you want to change the way the text is drawn, you must
//           override this method.
{
  CStr255 theText;
  GetText(aCell, theText);
 
  if (GetColWidth(aCell.h) > 0)
  {