Re: cleaning up FT2

[Werner LEMBERG]

> 'freetype2/include' is reserved for those header files that will be
> available to users of the library.  These should probably be
> installed in a directory like "/usr/lib/freetype/include" for a
> "freetype-devel" package on a typical Unix box.
> 

> 'freetype2/src/shared' contains header files that are used by
> several font drivers, but are not part of the public API.  We may
> move some of these later into include but for now, I prefer to keep
> them here.

After doing a `cvs -z9 update -dP' (which removes empty directories
also), I found the answer to my own question quite fast :-)

> > .) I strongly suggest that we avoid duplicated documentation.
> >    Functions, function types etc. should be documented in the *.c
> >    files, and only stuff not in the *.c files should be described in
> >    the *.h files (example: ftbbox.c vs. ftbbox.h).  It's a nightmare
> >    otherwise IMHO.
> >
> 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.

> I have commited it to "freetype2/docs/docmaker.py".  It's tiny
> python program.  For now, it only parses the documentation, builds a
> tree of objects for the documentation, then dump its contents in an
> unfriendly way (for debugging).

I'll test it.


    Werner