Notes on Documenting C++ 
=========================

Types of things a tech writer documents for a C program:
 * how to use a program
 * the command-line syntax
 * how to use the GUI
 * the API
 * code samples

Generalized sytax:
 * supply a value
 * optionally, supply a value
 * choose one
 * repeat of the item is allowed
 * repeat of the optional item is allowed

Supply a value
---------------
To indicate that the programmer must supply a value, use < >
	
Meaning:
	Replace  with an appropriate value.
Example:
 	MyProgram  
 where:
  	* arg is one of the following:
    	  copy -- copies startup files to outdir
     	  remove -- removes files from outdir
  	* outdir is an absolute or relative path
A valid interpretation:
  	MyProgram copy output/data
 
Optionally, supply a value
----------------------------
To indicate that a value is optional, use [ ]
	[  ]
Meaning:
	The item in the brackets is optional.
Example:
	[ abstract ]  () [;]
Interpretation:
	* the word "abstract" is optional
	* a value must be supplied in place of 
	* a value must be supplied in place of 
	* "()" must be provided after the name
	* the trailing semi-colon is optional

Choose one
----------
To indicate a choice between items, use |
	 |  | 
Meaning:
	Choose one of the items ( | means "or").
Example:
	us_citizen = true|false
Interpretations:
	us_citizen = true
	us_citizen = false

Repeat of the item is allowed
------------------------------ 
To indicate that an item may be repeated, use ...
	 ...
Meaning:
	The item before the ... may be repeated one or more times.
Example:
	print  ...
Interpretations:
	print myfile.txt
	print yourfile.txt myfile.txt *.doc

Repeat of the optional item is allowed
---------------------------------------
To indicate that an optional item may be repeated, use ... inside [ ]
	[  ...]
Meaning:
	If you provide the optional item, you may also repeat it.
Example:
	dir [  ] [  ...]
	where valid options are (etc...)
Interpretations:
	dir *.txt
	dir *.txt /od
	dir *.txt /od /w

API Documentation includes:
 * explaining to a customer how to interface his program with your program
 * explaining to a customer how he can make use of one or more classes (or
modules) that    you've made for him to use in his own programs

Defining and describing components:
 * variables -- datatype, name, purpose
 * functions
	- names
	- what each does (purpose or direction)
	- usage
		+ should be used "as is," alter source code, or subclass
the class
	  	  containing the function and override the function?
		+ what will call this function -- the user's own code or
part of the 		  		  program?
	- what each need to do its job (arguments)
		+ what does each arg represent?
		+ are there any guidelines or restrictions for the content
of the data?
	- what gets returned by each
		+ if the return type is "void", the function returns
nothing; otherwise, it 		                  returns the particular
datatype
		+ what is the meaning or purpose of the returned item?
	Syntax:
		[  ]   (
		[   [,   ...] ] )
	Example:
		static void getText()
	(if a modifier is "static," it is a class function; if not, it is
an instance function.
 * constructors and destructors -- what each does


Presentation of a function
--------------------------
void setValues (Properties newValues, int qty, char * label)
Properties getProps()

Styles of presentation:
* formal -- provide headings like Syntax, Purpose and Returns
* informal -- just show the syntax, describe the function and its returned
object, and provide an example

These details of a function should be easy for the reader to find:
* the function name (bullet, heading, TOC, index)
	the full syntax below could be condensed to setvalues(), or a
little better would be 	setValues(Properties, int, char *), because this
includes the datatypes, but no 	details.
* the formal syntax of each function and descriptions of any args
	void setValues (Properties newValues, int qty, char * label)
* the purpose of the function, and details about what it returns
* provide a function index before the individual function documentation


Documenting a constructor
--------------------------
Recommendation: Document all constructors except those that have no args
AND have no code inside their braces (do-nothing constructors).

All constructors can be grouped under a heading like "Constructors."

Suggested layout:
	[bullet] () -- 
Example for the Point class:
	Constructors
	* Point() -- creates a point at 0,0
	* Point(int x, int y) -- creates a point at x,y

Documenting a destructor
------------------------
If it exists, check with the developer to see if it should be documented.

Sample API structure
---------------------
Goal: don't go lower than heading level 2
Recommendation: devote an entire chapter to related classes:
* use [Chapter Title] for a category of classes
* use [Heading 1] for class names
* use [Heading 2] for:
  - Constructor heading
  - variable index heading
  - function index heading
  - heading/bullet for class variables; same for instance variables
  - heading/bullet for class functions; same for instance functions
  - headings that separate class from instance members
Consider what will appear in the table of contents

Example API doc structure
--------------------------
CarGrp
	The CarGrp class is for blah.
Function index
	A table that lists all the functions on right side and brief
description on left 	side.
addPiece(int,Image,int, ...)
 <- function name and types
	void addPiece(int angle, Image image, int upLeftX, int upLeftY,
int imgDimW, int 	   imgDimH, int imgOffX, int imgOffY
	* int angle -- angle of car in image
	* Image image -- master image contianing car image
	* int upLeftX -- x location of upper-left corner of car blah
	* more bulleted items here describing remaining int's
	The folowing example illustrates blah:
		Image master = (code);
		addPiece(45, master, 10,20, 4,5, 0,0);

another function, and so on