stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alessio Marchetti <std...@alessio.marchetti.name>
Subject Re: stdcxx documentation format
Date Wed, 07 Sep 2005 12:47:54 GMT
Lance Diduck wrote:

 > 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.

You are raising two interesting points:

1. Header files become difficult to read with too many comments.

I understand, but this is subjective.
I don't agree just because comments can be easily skipped when reading the 
header file as they are colored differently.
Additionally, with Doxygen it is possible to link a verbatim copy (with Doxygen 
commands removed) of the source in the generated documentation: users of the 
library don't need to view the headers to read the code (go to the verbatim copy 
instead, if they have a browser of course...).
The size of the headers will increase with comments inside and this can affect 
compilation time. Maybe this was implied in your comment.

2. Any change to the doc triggers a recompilation

Template-based code is recompiled even when there are no changes in the code and 
  I think compliers are smart enough not to recreate template instantiations 
when a comment changes.
Are there other facets I'm missing?

 > 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.

I'm not sure I understand: are you talking about the yellow box (the base class) 
at <http://www.alessio.marchetti.name/test/doxy/structtr1_1_1is__class.html> ?
I agree this is rather ugly!


Alessio

Mime
View raw message