Mailing-List: contact dev-help@stdcxx.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@stdcxx.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
Message-Id: <AFFEBA85-98E0-4655-BEFE-98A9D1487322@roguewave.com>
From: Eric Lemings <eric.lemings@roguewave.com>
To: dev@stdcxx.apache.org
In-Reply-To: <48606A98.3010300@roguewave.com>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v924)
Subject: Re: svn commit: r667636 -
 /stdcxx/branches/4.3.x/include/rw/_forward.h
Date: Tue, 24 Jun 2008 00:17:12 -0600
References: <20080613201606.7C7512388A0A@eris.apache.org>
 <CFFDD219128FD94FB4F92B99F52D0A499AA8A9@exchmail01.Blue.Roguewave.Com>
 <CFFDD219128FD94FB4F92B99F52D0A49010A3863@exchmail01.Blue.Roguewave.Com>
 <CFFDD219128FD94FB4F92B99F52D0A499AA8AB@exchmail01.Blue.Roguewave.Com>
 <CFFDD219128FD94FB4F92B99F52D0A49010A3868@exchmail01.Blue.Roguewave.Com>
 <485FBEA3.2020402@roguewave.com>
 <CFFDD219128FD94FB4F92B99F52D0A499AA8C1@exchmail01.Blue.Roguewave.Com>
 <CFFDD219128FD94FB4F92B99F52D0A4901DB05DD@exchmail01.Blue.Roguewave.Com>
 <485FDF62.6040606@roguewave.com>
 <CFFDD219128FD94FB4F92B99F52D0A499AA8C4@exchmail01.Blue.Roguewave.Com>
 <48606A98.3010300@roguewave.com>


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.