Introduction

Header comment templates are provided for

• C include files in ~fxa/templates/code/file.h,
• C implementation files in ~fxa/templates/code/file.c,
• C functions in ~fxa/templates/code/function.c,
• C++ (class declaration) include files in ~fxa/templates/code/File.H,
• C++ (class) implementation files in ~fxa/templates/code/File.C, and
• C++ functions in ~fxa/templates/code/function.C.

In the following templates, instructions to the coder are enclosed in angle brackets (<>). You are expected to replace the string <filename> with the name of the file and to delete other <instructions>, replacing them with comments or code as appropriate.

Many templates include labelled documentation sections. These labelled sections allow for automated extraction of documentation for inclusion in FrameMaker documents. Each labelled section is introduced by one or more label lines. For example, in the partial template for function.c (below), the first two lines are label lines:

/* -- global -----------------------------------------------------------------
/* -- fileScope --------------------------------------------------------------
** <function return type>
** <function name>(<parameter list including names and types or void if none)
**
** <brief function description including parameter descriptions and return
** code description, if not void>
** -------------------------------------------------------------------------*/
<function return type> <functionName>(<parameterList>)
    {
    }

Where there are multiple label lines, you are expected to delete all but the most appropriate one.

The following line places an RCS identification string into the file and assigns that string into a variable with a unique name.

static const char* const <filename>_h_Id =
  "$Id$";

This technique identifies the source file and all files which contain the code. Use the ident command. For example, if <filename> is replaced by demonstrateId and we use this file in building an executable named demonstrateId,

ident demonstrateId

will produce output including the following line.

$Id: demonstrateId.h,v 1.5 1994/04/23 00:17:51 leserman Exp $

file.h

The template for a C include file follows. A carriage return and nothing else must follow the #endif.

/* ---------------------------------------------------------------------------
** This software is in the public domain, furnished "as is", without technical
** support, and with no warranty, express or implied, as to its usefulness for
** any purpose.
**
** <filename>.h
** <very brief file description>
**
** Author: <original author>
** -------------------------------------------------------------------------*/
#ifndef _<filename>_h
#define _<filename>_h

#ifdef IDENT_H
static const char* const <filename>_h_Id =
  "$Id$";
#endif

<#include directives>

<declarations>

<function prototypes>

#endif

file.c

The template for a C implementation file follows.

/* ---------------------------------------------------------------------------
** This software is in the public domain, furnished "as is", without technical
** support, and with no warranty, express or implied, as to its usefulness for
** any purpose.
**
** <filename>.c
** <very brief file description>
**
** Author: <original author>
** -------------------------------------------------------------------------*/
#ifdef IDENT_C
static const char* const <filename>_c_Id =
  "$Id$";
#endif

/* -- module -----------------------------------------------------------------
**
** <The intended audience for this section is the client of this module.
**
** This documentation section is for a detailed overview of the contents
** of this file. Explain why these functions form a module. Give a brief 
** overview of the functions. Do not include details that are best documented 
** in function headers. If the functions are dependent on one another, 
** describe the dependencies. For example, maybe init() must be called once 
** and only once before any other function in this module.
**
** The module section must not include any implementation details. Do not
** discuss file-scoped static variables or functions in this section.>
**
/* -- implementation ---------------------------------------------------------
**
** <The intended audience for this section is the programmer maintaining this
** body of code. Include relevant implementation details such as the use of 
** file-scoped static variables and the relationships of functions, especially
** the use of file-scoped static functions.>
**
** -------------------------------------------------------------------------*/

<#include directives>

<#define directives (discouraged)>

<externally referenced variable definitions>

<static (file-scoped) variable definitions>

<static (file-scoped) function prototypes>

<function definitions>

function.c

The template for a C function follows. Choose one label line.

/* -- global -----------------------------------------------------------------
/* -- fileScope --------------------------------------------------------------
** <function name>()
**
** <This section is intended for client programmers. Include a brief function 
** description including parameter descriptions and return code description, 
** if not void. Do not include any implementation details.>
**
/* -- implementation ---------------------------------------------------------
** <This optional implementation section is intended for the maintainer of the
** code. Include interesting implementation details here.>
** -------------------------------------------------------------------------*/
<functionReturnType> <functionName>(<parameterList>)
    {
    }

File.H

The template for a C++ include file follows. A C++ include file generally contains the declaration of one class.

// ---------------------------------------------------------------------------
// This software is in the public domain, furnished "as is", without technical
// support, and with no warranty, express or implied, as to its usefulness for
// any purpose.
//
// <filename>.H
// <very brief class description>
//
// Author: <original author>
// ---------------------------------------------------------------------------
#ifndef _<filename>_H
#define _<filename>_H

#ifdef IDENT_H \\ <use #ifdef IDENT_TEMPLATE_H for templated classes>
static const char* const <filename>_H_Id =
  "$Id$";
#endif

<#include directives>

<declarations>

<class definition>

<inline function definitions>

#endif

A carriage return and nothing else must follow the #endif.

File.C

The template for a C++ implementation file follows. A C++ implementation file generally contains the member functions for one class.

// ---------------------------------------------------------------------------
// This software is in the public domain, furnished "as is", without technical
// support, and with no warranty, express or implied, as to its usefulness for
// any purpose.
//
// <filename>.C
// <brief class description>
//
// Author: <original author>
// ---------------------------------------------------------------------------
#ifdef IDENT_C \\ <use #ifdef IDENT_TEMPLATE_C for templated classes>
static const char* const <filename>_C_Id =
  "$Id$";
#endif

// -- module -----------------------------------------------------------------
//
// <The intended audience for this section is the client of this class. 
//
// This documentation section is for a detailed overview of the contents
// of this file. Explain class cohesion. Give a brief overview of the 
// functions. Do not include details that are best documented in function 
// headers. If the functions are dependent on one another, describe the 
// dependencies. For example, maybe the init() member must be called once 
// and only once before any other member.
//
// The module section must not include any implementation details. Discuss
// only those members and elements that are visible to clients.>
//
// -- implementation ---------------------------------------------------------
//
// <The intended audience for this section is the programmer maintaining this
// class. Include relevant implementation details such as the use of protected
// and private members and file-scoped static variables. Discuss the 
// relationships of non-public functions.>
//
// ---------------------------------------------------------------------------

<#include directives>

<static member variable definitions>

<static (file-scoped) variable definitions>

<static (file-scoped) function prototypes>

<function definitions>

function.C

The template for a C++ member function follows. Choose one label line.

// -- public -----------------------------------------------------------------
// -- protected --------------------------------------------------------------
// -- private ----------------------------------------------------------------
// -- global -----------------------------------------------------------------
// -- fileScope --------------------------------------------------------------
// <className>::<functionName>()
//
// <This section is intended for client programmers. Include a brief function 
// description including parameter descriptions and return code description,
// if not void. Do not include any implementation details.>
//
// -- implementation ---------------------------------------------------------
// <This optional implementation section is intended for the maintainer of the
// code. Include interesting implementation details here.>
// ---------------------------------------------------------------------------
<functionReturnType> <className>::<functionName>(<parameterList>)
    {
    }