Re: cleaning up FT2

[David Turner]

Hi Werner,

> > All right, I suggest removing documentation comments from the *.c
> > files.  However, we don't need to hurry. Let's simply consider that
> > the "reference" documentation is always placed in the headers.. that
> > will let us time to make the removal by hand when we see fit
> > (i.e. modifying source code..)
> 
> You want all docs in the headers?  I'm not really happy about this.
> IMHO the natural flow of documentation should be in the .c files
> instead -- .h files produce a synoptical view only, and since we
> intend to extract the docs anyway, there is no special need for a
> synopsis in the source code.
>
Well, I like to have structure and function descriptions in the public
header files. So let's say something like :

  - all header files in "freetype2/include" keep their comment
    (these can stay in the corresponding C files, or not, as you like)

  - in the case of type definitions, the comments are placed near
    them, which is in the header file

  - there are no comments for function declarations (except in "include"),
    as they should all be near the function definitions.

What do you think about this  ?

Cheers,

- David