Re: [boost] Re: Reference documentation

From: Ken Shaw (ken_at_[hidden])
Date: 2002-10-31 11:45:58

----- Original Message -----
From: "David Bergman" <davidb_at_[hidden]>
To: "'Boost mailing list'" <boost_at_[hidden]>
Sent: Wednesday, October 30, 2002 4:46 PM
Subject: RE: [boost] Re: Reference documentation

> (forgive me for speaking with a Java tongue here)
>
> A lot of the specification in the soft and fluffy world of Java is (at
> least partly) generated, via Javadoc, from the source code. Although, it
> does encourage a less strict process (yes, one should think before
> coding...), it is a very helpful process.
>
> For those of you not having (being forced?) to spend much time on the
> soft side, it goes as follows:
>
> /* ... */   - a comment, just like we are used to...
> /** ... */  - a Javadoc comment, ignored by the compiler (almost...),
> but cared by "javadoc", which generates HTML (actually, one can get it
> to produce any XML file, maybe even DocBook...). This is similar to what
> we have seen for many years in a lot of C++ and Pascal environments
> (instead of #pragma).
>
> In the example of a class "Foo", having the member function "void
> f(foo_t const&)", the code would look like the following:
>
>
> /*
>  This is a test C++ class, using Javadoc-style comments.
>  No, this does not make me a traitor ;-)
>  */
>
> namespace boost {
> Namespace test {
>
> /**
>  * This is a rather fooish class, doing fooish things.
>  * <p>
>  * The possible use cases are:
>  * <li><b>stand-alone</b> - what do you think?</li>
>  * <li><b>integrated</b> - just that</li>
>  * </p>
>  * In general this section of the comment can be rather lengthy, more or
> less
>  * constituting a specification. I do understand that most people do not
> feel
>  * comfortable typing HTML tags in this way, and that it does bloat the
> (uncompiled)
>  * code size a bit...
>  * @author David Bergman (making a fool out of himself by using
> Java-style
>  * (meta-)constructs)
>  * @see boost.lambda.memfun
>  */
> class Foo {
> public:
>   /**
>    * A Foo is constructed with an integer, <b>n</b> preferrable
> positive.
>    * @param n The integer embedded in a Foo, if a natural number it
> works,
>    * if a negative number, it will eventually fail
>    * @exception BadFooException If the number was too strange
>    * @see Bar#talkToFoo
>    * @see #f(foo_t const&)
>    */
>    Foo(int n) throw (BadFooException&) {
>    }
>
>    /**
>     * Do some magic thing to a {$link boost.foo.foo_t} structure
>     * @author Anonymous
>     */
>    void f(foo_t const& aFoo) {
> aFoo.magic = 42;
>    }
> };
>
> } // End of 'test' namespace
> } // End of 'boost' namespace
>
>
> ------------------------------------------------------------------------
> -----
>
> Does anyone know if there is a "javadoc" for C++ ("cplusdoc")? If not, I
> can investigate
> the matter.
>

doxygen can use Javadoc comments as well as it's own format. I believe that
synopsis can as well.

Ken Shaw