incubator-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 14:39:34 GMT
 

> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com] 
> Sent: Tuesday, June 24, 2008 6:55 AM
> To: dev@stdcxx.apache.org
> 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.

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

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.

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

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.

Brad.

Mime
View raw message