Re: [Doxygen-users] Making an Easy and fast readable C Library Manual reference.(TODO-Suggestions)

[Stephen G. <ste...@el...>]

I always try to develop code as libraries and, for anything but the most
trivial cases, also end up with one or two headers that the users of the
library need to include and a whole bunch that are only used between
compilation units within the library. This has held true whatever the
more general style of coding (C++, "plain C", "Object-style C",
whatever). In this situation, regardless of whether Doxygen is being
used or not, I have found that the best answer is just to introduce some
physical design into the setup. The one I start with looks like, for a
library called "baz",:

<my-work-area>/baz/
 -- holds all the public headers and the top-level Makefile

<my-work-area>/baz/m/
 -- holds the dot-c, dot-cpp files (compilation units) AND the
internal-use-only headers

So in your example, all of the headers would be moved down into the m/
directory, except for the four you've identified as "documented ones".

With this arrangement, before the introduction of Doxygen, there is
already scope for doing Interesting Things - eg, if someone wants a
pre-compiled set of all the libraries and the headers, a script can just
collect all of the <my-work-area>/*/ directories - so long as it doesn't
recurse any deeper it'll pick up only the public interface headers. And
of course humans can do the same thing ("Which of these files should I
be interested in?" "Just the ones in this directory"). You can also trim
down some of those convoluted header names, such as
"private_internal_xxxx.h" - this just becomes "m/xxxx.h".

When you add Doxygen into the equation you then have a very simple task:
just ask it to read all the headers in the <my-work-area>/baz/
directory. No need for special configuration directives to "hide headers
that have been explicitly not documented".

You can then start to get clever : Your public documentation has
Doxygen's recursive input switched off. If you have a second config file
with the recursion switched on and looking for the dot-c/dot-cpp files
as well, bingo, nicely formatted documentation of the internals of the
library for anyone who needs to maintain it :-)

Regards,
Stephen Goudge

> -----Original Message-----
> From: dox...@li...=20
> [mailto:dox...@li...] On=20
> Behalf Of Carlo Wood
> Sent: 20 November 2001 05:00
> To: Toni Moreno Gim=E9nez
> Cc: dox...@li...;=20
> dox...@li...
> Subject: [Doxygen-develop] Re: [Doxygen-users] Making an Easy=20
> and fast readable C Library Manual reference.(TODO-Suggestions)
>=20
>=20
> On Tue, Nov 20, 2001 at 04:37:37AM +0100, Toni Moreno Gim=E9nez wrote:
> > 3) (Disable File List Section)
> >
> > If you are documenting a like "Object Oriented C code" is=20
> common use a=20
> > couple of source code files for each "object."
> >
> > myobject.c
> > myobject.h
> >
> > But the final library usually have and unique header to include. By=20
> > example mi lib has while developing the first release aprox=20
> 25 headers
> >
> > but only one is needed to use the lib.
>=20
> Same thing here, at least I should be able to hide heaader=20
> files that I explicitely NOT documented (didn't add a \file=20
> in). Doxygen now generates this page:
>=20
> Here is a list of all documented files with brief=20
> descriptions: libcw/bfd.h [code]
> libcw/buf2str.h [code]			Definition of=20
> utility class buf2str
> libcw/char2str.h [code]			Definition of=20
> utility class char2str
> libcw/class_alloc.h [code]
> libcw/class_channel.h [code]
> libcw/class_channel_set.h [code]=20
> libcw/class_continued_channel.h [code] libcw/class_debug.h=20
> [code] libcw/class_debug_string.h [code]=20
> libcw/class_fatal_channel.h [code] libcw/class_location.h=20
> [code] libcw/class_marker.h [code] libcw/control_flag.h=20
> [code] libcw/core_dump.h [code]
> libcw/cwprint.h [code]			Definition of=20
> the utilities cwprint and cwprint_using
> libcw/debug.h [code]			This is the main header=20
> file of libcwd
> libcw/debug_config.h [code]
> libcw/debugmalloc.h [code]
> libcw/demangle.h [code]
> libcw/enum_memblk_types.h [code]
> libcw/lockable_auto_ptr.h [code]=20
> libcw/macro_ForAllDebugChannels.h [code]=20
> libcw/macro_ForAllDebugObjects.h [code]=20
> libcw/macro_Libcwd_macros.h [code] libcw/max_label_len.h=20
> [code] libcw/pc_mangled_function_name.h [code]=20
> libcw/private_allocator.h [code] libcw/private_assert.h=20
> [code] libcw/private_debug_stack.h [code]=20
> libcw/private_internal_string.h [code]=20
> libcw/private_internal_stringstream.h [code]=20
> libcw/private_internal_vector.h [code]=20
> libcw/private_set_alloc_checking.h [code]=20
> libcw/private_threading.h [code] libcw/private_TSD.h [code]=20
> libcw/strerrno.h [code] libcw/sysd.h [code] libcw/type_info.h [code]
>=20
> while I only want the four documented ones to appear.
> The user NEVER has to #include any other.
>=20
> --
> Carlo Wood <ca...@al...>
>=20
> _______________________________________________
> Doxygen-develop mailing list Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-develop
>=20
>=20