Mailing-List: contact stdcxx-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: stdcxx-dev@incubator.apache.org
Received-SPF: pass (asf.osuosl.org: domain of lancediduck@nyc.rr.com
 designates 24.29.109.7 as permitted sender)
Message-Id: <200509101520.j8AFKEMG018739@ms-smtp-03.rdc-nyc.rr.com>
From: "Lance Diduck" <lancediduck@nyc.rr.com>
To: <stdcxx-dev@incubator.apache.org>
Subject: RE: stdcxx documentation format
Date: Sat, 10 Sep 2005 11:20:32 -0400
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
Thread-index: AcWzqlC4MoFI3NAFTTSj8DlsczohIgCajlRg
In-reply-to: <431EE17A.6020407@alessio.marchetti.name>


Alessio Marchetti wrote:
<< 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?>>
The build system itself (ours or a users) cannot tell the difference between
a code change and a documentation change. The compiler will indeed skip over
the documentation, but the build system still invokes the compiler for every
translation unit depending on the file timestamp, no matter what changes.
The versioning system used is also based on file timestamps, and not what
actually changed in the file. Additionally, template libraries are released
in source code form -- this is stark contrast to the libraries normally
associated with compiled languages. Adding the documentation in with the
source code implies that the documentation follows the same identical
release process that the library itself does, and that the source code
follows the same release process that the docs do. 
But documentation changes depend more on source code changes than the other
way around --not that writing the user guide before designing a library
isn't a good idea, but in our case the library interface is already
specified by committee.
What I started doing with Doxygen is creating .ipp files that included the
.hpp files of interest. This had the desired effect of making the
documentation depend on the code, but not the other way around. See
http://www.stack.nl/~dimitri/doxygen/docblocks.html  

<< 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 >>
More that the generated documentation does not make any distinction between
the user interface and the implementation details.
http://www.alessio.marchetti.name/test/doxy/structtr1_1_1detail_1_1is__class
__impl.html  If we do use a tool like Doxygen (or any tool that generated
docs from code) then the source code will have to be separated or otherwise
account for how the doc tool works. This isn't hard though.  
Lance
-----Original Message-----
From: Alessio Marchetti [mailto:stdcxx@alessio.marchetti.name] 
Sent: Wednesday, September 07, 2005 8:48 AM
To: stdcxx-dev@incubator.apache.org
Subject: Re: stdcxx documentation format

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