Mailing-List: contact dev-help@stdcxx.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@stdcxx.apache.org
Received-SPF: pass (athena.apache.org: local policy)
Message-ID: <4860EE99.4040804@roguewave.com>
Date: Tue, 24 Jun 2008 06:54:49 -0600
From: Martin Sebor <sebor@roguewave.com>
Organization: Rogue Wave Software, Inc.
User-Agent: Thunderbird 2.0.0.12 (X11/20080226)
MIME-Version: 1.0
To: dev@stdcxx.apache.org
Subject: Re: svn commit: r667636 -
 /stdcxx/branches/4.3.x/include/rw/_forward.h
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>
 <AFFEBA85-98E0-4655-BEFE-98A9D1487322@roguewave.com>
In-Reply-To: <AFFEBA85-98E0-4655-BEFE-98A9D1487322@roguewave.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Eric Lemings wrote:
> 
> 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.
[...]
> BTW, I'm still trying to figure out what it is that you are proposing 
> exactly.  :D

We have an established (albeit undocumented) process and
infrastructure for documenting code and publishing the
documentation. The onus is on you and Travis to come up
with a proposal if you want to change how things are done.

So far you've decided on your own, despite my objections
and without establishing consensus, to start adding Doxygen
style comments to new headers, without reconciling the
differences between the existing process and your new one,
and without providing a clear path to such a reconciliation
in the foreseeable future.

Unless these issues are satisfactorily resolved and until
there is a viable plan for producing a adequate replacement
for the existing class reference on a reasonable schedule
I have to insist that the Doxygen comments be removed from
the newly added headers.

Martin