stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Sebor <>
Subject Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Date Tue, 24 Jun 2008 14:59:53 GMT
Eric Lemings wrote:
>> -----Original Message-----
>> From: Martin Sebor [] 
>> Sent: Tuesday, June 24, 2008 6:55 AM
>> To:
>> Subject: Re: svn commit: r667636 - 
>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>> Eric Lemings wrote:
> ...
>>> 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.
> I thought I did.  To repeat...for the record, write new documentation
> using Doxygen comments now.  Migrate the old HTML docs later.

Sorry. One sentence doesn't make a proposal, certainly not
one this vague.

>> 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.
> Hmm.  Let me see if I can summarize your objections:
> 1. You don't like Doxygen.
> I think that's pretty evident.  :)

Not at all. You completely misinterpreted what I said.

> Nothing wrong with that.  I think
> it's the best damn doc tool on the market...but that's just me.  But if
> you know of a better tool and/or format, we're all ears.
> 2. We shouldn't write any documentation comments because it's not
> conventional.

Nope. Again, you're missing my point. I'm saying changes
to process should be made only with a solid plan in place
and with consensus.

> Convention isn't really the right: this is becoming more like dogma.
> Travis and I both realize what this means -- breaking with this
> convention -- moving forward.  It's not easy writing docs and code at
> the same time, and the new code will look different from the older code
> (for a period of time at least), but it is the right thing to do we
> believe.

I disagree.

>> 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.
> And then what?  Hope that the documentation magically appears?  I'd be
> glad to remove it...if you have a better plan, solution, proposal...
> something in mind.

The current process is to maintain the existing docs in HTML,
using the existing infrastructure to publish the docs on the
site. You want to change it? Fine. Propose in detail how and
when this will change will take place and when we can expect
it to be done.

> But just removing the documentation comments is not "a clear path to
> such reconciliation in the foreseeable future" either.  It's the
> absolute last thing we should be contemplating in fact.

View raw message