Re: [boost] Reference documentation: one approach

From: David Abrahams (dave_at_[hidden])
Date: 2002-10-31 00:24:10

"Jeff Garland" <jeff_at_[hidden]> writes:

> > Synopsis supports configurable "comment proccessor backends". That's
> > one reason I'm interested in it. I want this because:
> 
> I'm confused isn't it the front-end parsing rule that that need to
> be different?

Front/back is a little weird here: The system's front-ends parse C++
code (and code for other languages) as input. The back-ends generate
output. So as I understand it, the front-end capture the comments and
the AST, while the back-ends process the comments to extract the
appropriate information.

> >    2. I don't agree that Doxygen does most of what we need. It is not
> >       designed for generic programs and metaprograms. We have different
> >       idioms from most OO systems that Doxygen is designed for and
> >       they will need to be supported.
> 
> You and I disagree on this point generally, but I don't waste
> anyone's time debating this.  

OK. I wouldn't debate much anyway, since I'd be arguing with little or
no data. I tried Doxygen once a few years ago and gave up quickly.

> I'm back to my original view that we should ignore doc generation.

I'm certainly not going to ignore it, but I guess people may decide
not to discuss it. Even if I only get really good implementation docs
out of Synopsis, I'll be highly satisfied.

> That is, I agree with Doug what we really need is a standard form
> that generators can create or can be created by hand and then
> massaged appropriately for output into html, pdf, etc.

I find the question of intermediate format uninteresting. Anything
sufficiently rich will do, as long as I don't have to edit it
myself. I also agree with Doug that keeping documented interfaces in
synch with the code is a real concern.

> Whatever. I could care less about the details of the syntax.  

I guess that's where our fundamental differences lie. I think that
unless the syntax for the programmer is easy, accessible, and
attractive, programmers won't use it at all.

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com