On Jun 23, 2008, at 9:31 PM, Martin Sebor wrote:
Travis Vitek wrote:
Martin Sebor wrote:
[...]
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
Since we aren't providing any html documentation for any c++0x code
at
this time, maybe we should stop using html documentation? :P
So the options are--
a) not document the c++0x code at all
b) write up documentation for all new code in html
to be consistent with what is used currently
c) move all existing documentation over to doxygen
before a single doxygen comment is added to the
new code
Assuming we want to have C++ 0x fully documented in 5.0 or shortly
thereafter which of (b) and (c) do you think is viable?
I don't think any of those choice are viable _in the near term_ but if
I had to choose?
C. If only to get a better idea of how much work we're really talking
about.
But I don't think doing that right now is really necessary. I think
we all agree, there's too much C++0x work to be done in the near term
that virtually prohibits migrating the old HTML docs right now. But
that doesn't mean we should not be writing new documentation.
...
I know that at Rogue Wave we have an xslt that transforms from
doxygen
generated xml files to html documentation, so unless using doxygen is
totally ruled out, that can be used to bridge between the old html
pages
and generated ones.
Yes, but the transformation isn't fully automated and according
to Marc requires quite a bit of human intervention. It's clear
that we don't have the bandwidth to take this on and still make
our target date.
I agree... to a degree. We don't have the bandwidth at present but it
is not at all clear (to me at least) how much work this migration will
really require.
...
For starters, what prevents me from browsing all new Doxygen docs
is that there is no generated HTML documentation. I and everyone
else would have to install Doxygen and compile the HTML docs
ourselves to get the benefit.
I don't think there's anything that prevents us from copying and
redistributing our own documentation. You only need Doxygen installed
if you need to regenerate the docs for some reason.
And because the docs aren't being
generated and the generated HTML looked they're likely to contain
all kinds of formatting problems.
I've generated them. And yes, there are formatting problems.
...
Doxygen doesn't have to document everything that it sees. There are
many
ways to control what will be documented. You can tell it to only
generate documentation for things that have doxygen style comments or
you can mark things as internal so the documentation can be
conditionally disabled.
I've seen the libstdc++ documentation (see below) and talked to
the project's maintainers. My understanding is that they're not
completely happy with it for some of the same reasons I've raised
here and are considering (or maybe even working on) migrating away
from Doxygen to some other tool/format.
A better tool/format than Doxygen? Wow. I'd be interested in reading
that thread of discussion! Link?
BTW, I'm still trying to figure out what it is that you are proposing
exactly. :D
Brad.
