> -----Original Message----- > From: Martin Sebor [mailto:[EMAIL PROTECTED] > 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.
