Re: [Devel] FreeType documentation comments

[David Turner]

Hi Graham,

Graham Asher a écrit :
> 
> 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
>
When I designed the original comment format, I was using an editor that didn't
perform character deletions when the backspace key was pressed. This was very
helpful to deal with the boxes.

However, I'm now using other editors, and as a consequence, the documentation
generator supports several block formats. I advise you to look at the content
of src/tools/docmaker.py, there are comments (no pun intended) explaining this.

Right now, all new comments I add have the following format:

  /**************************************
   *
   * @type: A_Type
   *
   * @description:
   *    bla bla bla bla bla
   *
   * @note:
   *    foo
   */

this is quicker to type and to update with most editors. The documentation 
generator
could also be updated to support a minimalistic format like /** ..... */, but I 
like
having a big vertical bar of asterisks, since this helps a lot in spotting 
comments
in the source code, especially when using a stupid editor like vi that doesn't
perform syntax highliting, or when printing your code..

 
> 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.)
>

That's probably not a problem with the documentation format :-) But it probably
needs attention. There are certainly a few updated comments in the sources, but
I believe that's the exception, not the norm...

If you have suggestions for improvements, we'll gladly accept them, preferrably
as patches ;o)
 
> 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.
> */
> 
You can already avoid boxes, and I still strongly encourage using a vertical
indent of asterisks. On the other hand, there's no way that one can produce
high-quality structured and cross-referenced documentation without using
any kind of tagging.

The fact that '@' is used instead of '\' (standard on JavaDoc and Doxygen)
comes from the fact that the former is a lot quicker to type on my French
keyboard. Again, DocMaker could be trivially changed to support a different
format. Markers/Tags can already be written alternatively as "<Tag>" or
"@Tag:" anyway..


> 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.
>
Comments are placed in header files intentionally: since these are always
installed with "devel" packages of the library, a developer writing an
application that uses FreeType can parse its public header files directly
to obtain documentation on the APIs he/she's using.

That's also why it's so important to have very readable documentation
comments. This also saves time when developing or working on the library,
in my own experience..

So the rule is that the documentation comment goes above the declaration.
Except for internal (static) functions, for example, who generally don't
need a sophisticated formatted comment anyway.

 
> 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.
>
Except that you need a documentation generator that understands C, and is
capable of understanding the meanings of FT_EXPORT(), for example.

Since I wanted DocMaker to be simple, performing this kind of analysis
was out of the way. Moreover, I find placing the identifier in the comment
cleaner, since it also allows to tag its 'class' (i.e. type, struct, function,
functype, enum) and makes for better presentation IMHO.

Be aware that I originally tried to use Doxygen for this task, but I was
less than pleased by its complexity and the quality of its output. I finally
prefered to write a small Python program to perform the same task, and I
consider that it took me less time than if I wanted to master Doxygen to
have it parse the FT2 public headers and generate output that is as nice
as the current API Reference is (even if it itself isn't perfect), while
having something very readable in source form.

 
> 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 ...
> */
>
But my personal preference goes to

/****************************************************
 *
 * @function: TT_Load_Any
 *
 * @description:
 *   load any font table into a buffer supplied by
 *   the caller
 *
 * @input:
 *   face   :: the face containing the table
 *
 *   tag    :: that tag of the table to load. Use the
 *             value 0 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; ...
 */

Since I find it a lot quicker to grasp. Especially the meaning
of each argument since these are well spaced.
 
> I am making these suggestions based on my work in creating and maintaining
> large libraries for various clients including Symbian, Psion and Slangsoft.
>
My experience is very different from yours, and I'm currently working
on a _very_ large software project where _all_ documentation is produced
through JavaDoc. The comments found in C, C++ and Java sources are a
terrible mess. Developers apparently didn't bother to make the comments
readable in plain text since they assumed that the documentation generator
would "pretty-print" everything in HTML.

Unfortunately, most of the comments are simply wrong or out-of-date.
Developers never realized this because they never read JavaDoc's
output anyway, and they never read their own ugly comments either.

And there are about 100.000 comment lines like this. Debugging's
never been so funny :-)

So, I strongly believe that the quality of documentation has very few
relationships with the tools used to produce it (though this is not
true for its _structure_), or the size of the project involved.


> 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.
>
I hope you'll appreciate the fact that boxes are optional. I do not think
that the points you raised justify a complete change of the documentation
system, even if it still can be improved in certain ways... (for example,
it shouldn't be difficult to generate documentation to process them with
Doxygen in order to generate PDFs or man pages automatically).


Best Regards,

- David Turner
- The FreeType Project  (www.freetype.org)