Re: [Devel] FreeType documentation comments

[Werner LEMBERG]

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

That we have that many boxes is my `fault'.  To have overall
consistency, I intentionally changed all comments to the box format.

> Right now, all new comments I add have the following format:
> 
>   /**************************************
>    *
>    * @type: A_Type
>    *
>    * @description:
>    *    bla bla bla bla bla
>    *
>    * @note:
>    *    foo
>    */

Please use this:

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

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

I fully agree.

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

Well, on an English keyboard (which I use) it is not so convenient...

> /****************************************************
>  *
>  * @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; ...
>  */
> 

I suggest a slightly different format which is easier to edit if
something changes:

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

If you agree, I will slowly convert all comments to that format; I
think it is an interesting exercise to write a small sed program to do
that semi-automatically :-)

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

Some years ago I've sent some test output from my (oold) c2cweb tool
which generates pretty-printed TeX output.  cweb parses the C code to
a certain extent, so it can do very clever things; the most useful
feature is an index of all used variables and functions.  In case you
are interested I can prepare an example again.


    Werner