RE: [boost] Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-10-30 22:25:34

> 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?
 
>    1. I hate weird junk in comments; From most of my code you could
>       pick up exactly what to put in the docs with just the
>       appropriate comment processor and no directives. For the rest, I
>       really like non-intrusive syntactic constructs like those of ReST.

Ok.
 
>    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.  I'm back to my original view that we should ignore doc
generation.  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 believe that the doxygen commenting format will handle almost all of
> > Doug's list and those that it doesn't can be added.  So, for example
> > we a fully annotated function would look something like:
> > 
> > //! This is the brief comment for a function /*! This is the long
> > comment for the function.
> >     ...
> >     ... still the long comment....
> >   @param foo Description of the foo parameter
> >   @param bar Description of the bar parameter
> >   @return Description of the return value
> >   @pre Precondition 1
> >   @pre Precondition 2
> >   @post Postcondition 1
> >   @throws Exception commentary
> 
> Yuck!
> 
> That should be:
> 
>         // foo - description of foo parameter
>         // bar - Description of the bar parameter
>         // Returns: Description of the return value
>         // Preconditions: Precondition 1; Precondition 2
>         // Postcondition: Postcondition 1
>         // Throws: Exception commentary
> 
> *Now* you get the idea 

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

Jeff