Eric Lemings wrote:
-----Original Message-----
From: Travis Vitek [mailto:[EMAIL PROTECTED]
Sent: Monday, June 23, 2008 10:13 AM
To: dev@stdcxx.apache.org
Subject: RE: svn commit: r667636 -
/stdcxx/branches/4.3.x/include/rw/_forward.h
Martin Sebor wrote:
Eric Lemings wrote:
Gah. I have to update my docs as well: template parameters are
documented using the @tparam tag rather than the @param tag.
I thought we said we wouldn't be using doxygen comments in
library code. Am I misremembering?
I know that it was requested that I remove the doxygen
comments from the
type traits stuff I have been working on, but I decided it
would be best
to commit them with the comments intact and remove them only if
necessary. I mentioned this to Brad in our off-list
correspondence, and
he has opted to do the same.
As I sit here thinking about it, I can't remember exactly why it was
decided that they should be removed. Perhaps it is best to have this
discussion again, but on the list this time.
To start, I'm not sure I understand the motivation for _not_ using
doxygen in the library headers. I realize that having documentation in
the code is a departure from what stdcxx has done in the past, but I'm
not convinced that this is a bad thing.
I'll add a couple points to that for the record.
Much of this was precipitated when I noticed that GNU libstdc++ also
includes their documentation right in the library headers and source
code. Why? Because most, if not all, C/C++ preprocessors will strip
comments by default during a first pass. Thus, the impact of extensive
documentation comments on overall build times is negligible.
Of course preprocessors strip comments. It's required by
the language standards. But regardless of the translation
stage at which the stripping takes place, it isn't without
cost.
I gave a number of arguments against Doxygen comments in
stdcxx headers:
1) existing code doesn't use it and converting the raw HTML
docs to Doxygen is an enormous task that none of us has
the time to take on; Doxygenating new code without doing
the same for the existing code is inconsistent and won't
help us produce end-user documentation for the finished
product
2) Doxygen markups are harder to read than ordinary comments
(see 3), and in the library headers the volume of such
comments will, in many cases, dwarf the amount of code
3) unless/until there is infrastructure to generate the HTML
docs from the Doxygen comments documenting the library (or
other parts of stdcxx) using Doxygen markups serves no
purpose
4) the HTML generated from stdcxx headers is unavoidably
ugly because of the necessity to uglify names (leading
underscores, etc.)
Martin
