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: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Date Tue, 24 Jun 2008 03:31:36 GMT
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?

> 
> Another important point is that the stdcxx project doesn't have anyone
> volunteering time to write documentation. If we want the documentation,
> we're likely going to have to do it ourselves, and I find using doxygen
> comments _much_ simpler than writing html.

I agree. But that won't help us migrate the reams of existing docs
to Doxygen. Without the migration I see no point in documenting new
code in one format and old code in another. A substantial amount of
C++ 0x code will also involve changing the old code (such as adding
new member functions to containers or adding requirements clauses).
We can't very well document these changes in Doxygen and leave the
existing HTML docs unchanged.

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

> 
>> 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
> 
> If the code is well written, comments are usually reserved for
> situations where they are necessary to describe what the code is
> actually supposed to be doing. Most frequently this type of comment
> would be found in the body of a function definition. Doxygen comments,
> on the other hand, usually appear with the declarations, so the type of
> comments that you would usually need to read aren't necessarily in the
> same place as the doxygen comments. Additionally, your editor can likely
> be configured to hide the doxygen comments if you don't want to see
> them.

I've seen Doxygen comments. A simple example of the differences
is the recently added Doxygenized documentation of the rw_prinf()
format specifiers vs what we had before. I find the original raw
text comments much more readable than the only moderately heavily
marked up replacement.

> 
> As for readability, consider this. There are currently no comments
> describing what a given library class or function is expected to do. If
> you want to see what the expected behavior is, you get to walk yourself
> through the implementation, or you get to fire up a web browser and look
> at the html documentation. If the documentation is added as doxygen
> comments, they are in the code. They may be slightly less readable than
> plain english text due to the additional markup, but there is _nothing_
> that is stopping you from looking to the implementation or firing up a
> web browser like you did before.

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. And because the docs aren't being
generated and the generated HTML looked they're likely to contain
all kinds of formatting problems.

> 
>> 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
> 
> Which would you like first, the chick or the egg? The infrastructure
> will never be built to generate html documentation from doxygen comments
> if we don't have doxygen comments to generate documentation from.

FYI: We've had Doxygen comments in place for parts of the test
driver (including the whole exec utility) in place for two years
now. No one has had the time or the energy to set things up. I
don't see anyone stepping up and tackling any of the open
documentation issues, including STDCXX-964.

But to answer your question, I believe the infrastructure to
generate the docs must be in place first, just like build
infrastructure needs to exist before any non-trivial amount
of code can be written. AFAIK, Doxygen can be run on straight
source code with no markups.

> 
>> 4)  the HTML generated from stdcxx headers is unavoidably
>>     ugly because of the necessity to uglify names (leading
>>     underscores, etc.)
[...]
> 
> 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.

http://gcc.gnu.org/onlinedocs/libstdc++/api.html

> 
>> Martin
>>


Mime
View raw message