Re: [Devel] FreeType documentation comments

[David Turner]

Hello all,

not to let a good thread die :-)

Werner LEMBERG a écrit :
> 
> > > 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.
>
Ahh, I didn't noticed that, since I mainly look at the output of "DocMaker"
now to check documentation :-)

Maybe it'd be a good idea to change everything to the format you just suggested.

Of course, it's possible to do that with a sed script, but these things have a
tendency to be _very_ hard to understand and maintain when they perform 
non-trivial
tasks. And you already know my strong dislike of Perl anyway :-)

So, I think that a _reasonable_ way to do that would be to modify "DocMaker" to
create a new tool to reformat all documentation comments within the FreeType
headers. This would allow strong consistency easily.

And if we allow for some little flexibility, this would also probably allow
Graham and others to write their own comments in "super fast typing mode",
granted that they follow a few simple tagging rules, letting the task of
correct formatting to the Python script


On the other hand, I don't have much time to implement that right now, since
I prefer to focus on the code (more on this later)..

In all cases, I believe that the _final_ comments found in the released
sources should always be as clear and legible as possible.

Any comments on this idea ??


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

Any reason why the "A_Type" shouldn't be on the same line that
the first marker ("@type:" here) ? I find it useful to quickly
spot the definition of a specific type, since I enter
"@type: <MYTYPE>" in the "Find in files" dialog of my text editor

Other than that, I don't have any objection to do this, but I'd
like to know the reason, if there is any that isn't pure
"consistency"

 
> > 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...
>
<joke> You should use a German keyboard. And then you'll discover that
       Emacs is clearly unusable at high speed on anything that isn't
       QWERTY :-) </joke>

Appart from that, I don't think that the documentation format should be
tailored to a specific editor. I absolutely abbhor Emacs and Vi, but that's
just personal taste and I'd be sadly depressed if using one of these was
a requirement to write nice code :-)

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

Many functions have parameter descriptions that can fit on a single line,
and adopting this scheme in all cases would probably expand the comment
sizes greatly with little benefit.

Again, a script could handle all of this automatically and "compact" the
comments when everything fits on one line, or use your format for things
more complex or lengthy..

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

I believe that a Python program would be much more useful and understandable.
See, I can learn the sed syntax, but I always happen to forget it completely
after a few weeks.
 
> > 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.
>
 
I don't know if I'm interested in something too complex. Sophisticated
tools are generally difficult to maintain and use, and it's be good if
we had something simple enough to be understood by any new developer.

Best Regards,

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