stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eric Lemings <eric.lemi...@roguewave.com>
Subject Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Date Tue, 24 Jun 2008 06:17:12 GMT

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.


Mime
View raw message