RE: [ft-devel] non-standard commenting in tttables.h

[Turner, David]

Hello,

the different conventions are part of history. I prefer the
@tag: syntax myself because it's much faster to type on my
keyboard, and because it's a little "lighter" when you read it
:-)

by the way, I hate writing Text documents and the Dos/Windows
command shell, because \ is typed as AltGr-8 on my French Azerty
keyboard, and that's painful.

Oh yes, @ is AltGr-0, but I don't have problems with that at
all. The difference 2 centimeters make :-)

Apart from that, you don't need to put the function name on the
following line, all of the following are valid:

-------------------------
  @func: func_name

  @desc: description

  @note: do this and that
--------------------------
and
--------------------------
  @func:
     func_name

  @description:
     function description

  @note:
     do this and that
--------------------------

note that "desc" is used as a short-hand for "description"

also the "open block convention", i.e.

/**
 *
 *
 */

is much more convenient because it allows you to edit the content
of the comment without having to reformat the right column as in

/**********************************
 *                                *
 *                                *
 **********************************/

all of this is handled by "docmaker" transparently anyway. The tool
reports errors when it finds them anyway (e.g. bad cross-references)

don't be too focused on conventions. My anecdotal experience taught
me that the little following principles are what's important:

  1 - the documentation comments should be as *readable* as possible.

  2 - the API documentation should preferably in the headers, or the
      source files, and certainly not some external files.

the first point comes from two observations:

  - readable comments can be understood instantly. like code,
    you'll end up reading them alot, and you don't want to spend
    your time decyphering bad formatting.

  - readable comments tend to be updated more easily. If you can
    grasp it immediately, you automatically figure what to update.

the second point comes from the fact that it's trivial to forget
to update "external" documentation files, meaning that your comments
begin to rot and *mistaken* your users. Unless you have very stringent
tools to ensure everything works well, external API docs are a bad
idea.

Of course, it can happen with source comments, but it's a lot
less likely because you can update the doc right when you change the
function, instead of locating some doc file somewhere else, eventually
starting an XML editor or something like that... Unless your life
is deeply tied to a mammoth like Emacs, that's not a good idea :-)

But any tool like "docmaker" is useless without developers willing
to use it properly. I have no problem writing doc comments with the
format used in FreeType, since that's what I use exclusively for my
own projects (either personal or professionnal).

Where I work, we have thousand of doc comments using the default Doxygen
tags which are essentially use-less. The developers have created the
doc comment because they were required to, but didn't care to write
anything understandable. so, you end up with lots of things like this:

-----------------------------------------------------------------
/*! \fn t_FooSpduBuffer _FooGetSpduBuffer(UChar * param1)
 *  \brief Retrieve the SPDU and store it in a buffer after
 *   analysing parameter evtParam1 in event EV_FOO_SPDU_RCV.
 *   Several buffers are concatenated into a single one to help
 *   analysis.
 *  \param UChar * param1 : EvtParam1 to analyse
 *  \return
 *   t_FooSpduBuffer : <BR>
 *   The received SPDU as a buffer.
 */
t_FooSpduBuffer _FooGetSpduBuffer(UChar * param1);
-----------------------------------------------------------------

How is this readable within 5 seconds ? Now repeat the process for
every API in the library.... And I don't even talked about the
content of this doc which describes implementation details instead
of functionality... baaah

Oh well, just my little rant about lazy developers....

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


> -----Message d'origine-----
> De : address@hidden
> [mailto:address@hidden
> la part de
> Hisashi T Fujinaka
> Envoyé : mercredi 26 octobre 2005 23:28
> À : Werner LEMBERG
> Cc : address@hidden
> Objet : Re: [ft-devel] non-standard commenting in tttables.h
>
>
> On Wed, 26 Oct 2005, Werner LEMBERG wrote:
>
> >> Thanks!  I guess I have other questions as well. Some functions are
> >> marked on the previous line with "<Function>" and other are marked
> >> with "@function". Is one more correct than the other?
> >
> > We have two styles:
> >
> >   /***********************/
> >   /*                     */
> >   /* <Foo>               */
> >   /*   ...               */
> >
> > and
> >
> >   /***********************
> >    *
> >    * @foo:
> >    *   ...
> >
> > I prefer the former (which is the old one -- many people think it is
> > too clumsy), while David prefers the latter (which is the
> new one and
> > obviously `lighter').  It basically makes no difference since both
> > formats are supported by our `docmaker' tool to create the
> > HTML-documentation.
>
> Thanks. I was just using "grep" to find function names and saw some
> disrepancies. I guess there aren't that many using the latter format
> quite yet, at least for functions.
>
> I did find some discrepancies:
> ftsysmem.h doesn't put the function name on the the following line for
> ft_memory_new and ft_memory_destroy,
>
> cache/ftccmap.h uses a mixed format in FTC_CMapCache_New and
> FTC_CMapCache_Lookup,
>
> ftcache.h uses a mixed format in FTC_CMapCache_New and
> FTC_CMapCache_Lookup,
>
> fttrigon.h has a lot of mixed format function comments,
>
> freetype.h has a mixed format function commen for FT_Stream_OpenGzip.
>
> I'm sure not many people care that much, and honestly the
> only ones that
> are really bothersome to me are the two in ftsysmem.h (and I
> don't know
> if I even need to go poking around in there.)
>
> --
> Hisashi T Fujinaka - address@hidden
> BSEE(6/86) + BSChem(3/95) + BAEnglish(8/95) + MSCS(8/03) +
> $2.50 = latte
>
>
> _______________________________________________
> Freetype-devel mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/freetype-devel
>
***********************************************************************************
Information contained in this email message is confidential and may be 
privileged, and is intended only for use of the individual or entity named 
above. If the reader of this message is not the intended recipient, or the 
employee or agent responsible to deliver it to the intended recipient, you are 
hereby notified that any dissemination, distribution or copying of this 
communication is strictly prohibited. If you have received this communication 
in error, please immediately notify the address@hidden and destroy the original 
message.
***********************************************************************************