Boost logo

Boost :

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.

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


Boost list run by bdawes at, gregod at, cpdaniel at, john at