[Devel] FreeType documentation comments

[Graham Asher]

I suggest that we change the FreeType documentation comment format. At the
moment many of the comments are wrong, and they are hard to update.

WHAT IS WRONG

1. The comments are enclosed in unnecessary and in my opinion rather ugly
boxes, made of asterisks, that have to be carefully repaired after any edit,
and

2. Comments are duplicated. For example, the comment explaining the function
TT_Load_Any is found in both sfnt.h and ttload.c. And it's wrong in both
places (the reference to MAKE_TT_TAG needs to be changed to FT_MAKE_TAG, and
the ready-made tags in tttags.h should be mentioned.)

WHAT WE SHOULD DO

My suggestion is that we should do the following:

1. Change to a format that supports popular automatic documentation
generators like JavaDoc, but do NOT put boxes around comments, which are
unnecessary and time wasting and luckily not required by the documentation
generators. Also, don't use keywords and stuff starting with '@', by
preference - keep it plain text. Thus a documentation comment starts with
/** and looks like this:

/**
This is my function.
*/

2. Comment functions and other objects in ONE place only. This should be
just above the function definition in the C source file, or, for structures
and other things that live only in header files, in the header file. The
rule is that if an object has a separate declaration and definition, the
comment goes above the definition.

3. The function name is not needed in the comment. It can easily be picked
up by the documentation generator - or the human reader. Putting it in just
causes errors when the function is renamed.

Thus the comment to TT_Load_Any becomes:

/**
Load any font table into a buffer supplied by the caller.

Input arguments:

face: the face containing the table.

tag: the tag of the table to load. Use the value 0 if you want
to access the whole font file, else set this parameter
to a valid TrueType table tag that you can create with
the FT_MAKE_TAG macro; or use one of the ready-made
tags defined in tttags.h.

... etc ...
*/

I am making these suggestions based on my work in creating and maintaining
large libraries for various clients including Symbian, Psion and Slangsoft.
The most important point is not the use of a documentation generator - most
serious developers look at the source, but the simplicity of the format (no
boxes or interminable rows of asterisks) and the elimination of duplicate
comments.

Graham Asher