Re: [boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-29 15:21:22

On Tuesday 29 October 2002 10:31 am, William E. Kempf wrote:
> Douglas Gregor said:
> > I looked at DocBook a bit, but I'm no expert in it. With DocBook alone
> > we  can't express our reference documentation by the C++ code structure
> > and end  up with a useful document.
>
> You can't?  I'm not a DocBook expert, as pointed out in another posting.
> But I thought the DocBook structure was specifically open ended enough to
> allow for complex structures similar to what we need?

Sorry, my claim may very well just be FUD. I'll research DocBook more before 
drawing such a conclusion.

> > The answer is probably to use both. The overall document structure comes
> > from  DocBook, but the nitty-gritty C++ reference details are specified
> > with some  simple C++ declaration/documentation DTD and transformed into
> > DocBook.
>
> Sounds like a reasonable approach.  My concern is still the complexity,
> however.  Developers make lousy enough documentors as it is.  Make it more
> difficult for them to write the documenation and I bet you'll see the
> quality go down even more.  Not to mention you may very well scare away
> some potential Boost submissions if we require them to use this stuff,
> even if it stems solely from FUD and not fact.

My hope was that if reference documentation is centered around C++ structure 
(which developers know), with tags clearly specifying what information they 
should give (return type, function parameters, template arguments, 
requires/effects/postconditions/throws/etc. clauses), it would become easier 
to write reference documentation. Maybe that's just wishful thinking :)

> I'm very interested in this, regardless.  So maybe some of us should
> collaborate on our research and findings?

Absolutely.

        Doug