incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Sebor <se...@roguewave.com>
Subject Re: stdcxx documentation format
Date Wed, 07 Sep 2005 17:29:29 GMT
Lance Diduck wrote:
> 
> Comments on using Doxygen with tr1
> 
> 1. It is hard to implement a portable tr1, esp type_traits. Making a type
> traits that Doxygen understands as well ....

...would lead to even more configuration macros in the code?

FWIW, one of the stdcxx "design principles" is to hide complicated
preprocessor logic behind functional macros. There is one central
place where these macros are #defined based on the results of
configuration for a given platform: include/rw/_defs.h. The rest of
the library sources are relatively free of preprocessor conditionals.
The result is pretty clean looking code, but it's code that may not
mean much to the user of the library unless he is familiar with the
meaning of each of the macros.

Is Doxygen capable of expanding such compiler-dependent macros (i.e.,
of running the preprocessor)? If so, how good is it at reformatting
ugly code that usually results from the preprocessing of complicated
(often multi-line) macros. How does it deal with the ugly names of
function or template parameters (i.e., those with leading underscores).

> 2. Putting the documentation in the code always sounds like a good idea, but
> consider that in the STL most of the docs would go in headers, that any
> change in headers (including docs) forces a recompilation and a new release
> of code, that source headers are already busy with copyright notices,
> revision and other coder comments not relevant to a user, porting macros,
> and other things.

I'm not sure I see the problem with having to recompile after a doc
change, but I would be concerned with the effect of extensive comments
(tables filled with various data, examples, etc.) on compilation time.
I am also concerned about the size of the documentation dwarfing the
actual code in the headers and increasing the maintenance costs.

> Using Doxygen to document the test drivers, and generating docs from there I
> have found to be a little easier to manage.  
> 3. Doxygen works best like this:

Interesting. I've always assumed most of the documentation would go
in the headers and only internal (i.e., maintainer) docs would be in
the sources.

[...]
> However template metaprograms, are almost nothing but declarations. It is
> possible to get Doxygen to read this and put in the links, but separating
> out the "implementation" (i.e. the detail code) from the "interface' is
> solely a job of the documentation.

True. From Alessio's response it looks like Doxygen is smart enough
to know how to extract the declaration from a definition.

> Before choosing Doxygen I would try
> documenting a few template metaprograms with it first.

Agreed. It would help to see some "real world" examples, preferably
using stdcxx sources (or something similar).

Martin

Mime
View raw message