Re: [boost] Reference documentation: one approach

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

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 

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