From: David Abrahams (dave_at_[hidden])
Date: 2002-10-30 16:30:16
"Jeff Garland" <jeff_at_[hidden]> writes:
> Well I had given up on generation, but maybe I was premature. One
> topic we might discuss is the format for putting these sorts of
> comments in the code. I would suggest we recommend we Doxygen 'syntax'
> for this (this would be a recommendation not a hard requirement).
> There are several reasons:
> 1) It is well documented and widely used 2) Apparently both Doxygen
> and Synopsis will support it (Dave does Synopsis specify it's own
> format for this -- I didn't see it on the website?) 3) It probably
> covers 95% of what we need. 4) It is pretty logical
Synopsis supports configurable "comment proccessor backends". That's
one reason I'm interested in it. I want this because:
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.
> 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
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
-- David Abrahams dave_at_[hidden] * http://www.boost-consulting.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk