Boost logo

Boost :

From: David Bergman (davidb_at_[hidden])
Date: 2002-10-30 17:46:12

(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
 * constituting a specification. I do understand that most people do not
 * comfortable typing HTML tags in this way, and that it does bloat the
 * code size a bit...
 * @author David Bergman (making a fool out of himself by using
 * (meta-)constructs)
 * @see boost.lambda.memfun
class Foo {
   * A Foo is constructed with an integer, <b>n</b> preferrable
   * @param n The integer embedded in a Foo, if a natural number it
   * 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} 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.

I think it would be perfect to have (preferrably XSLT) transformations
taking the XML output of such a "cplusdoc" tool and merging it with
separate specification documents (in DocBook?) to produce an extended
DocBook document.


-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of Greg Colvin
Sent: Wednesday, October 30, 2002 4:57 PM
To: Boost mailing list
Subject: Re: [boost] Re: Reference documentation

At 01:45 PM 10/30/2002, you wrote:
>There has been some talk about wanting to extract documentation from
>source code. I'm not sure that this is a good idea. After all, we
>to document a *specification*, not an *implementation*.

I share this concern.

> (If you're
>writing an implementation guide, feel free to ignore everything that
>follows.) Ideally, one should write the documentation *first*, then
>implement. Yes, I know that, especially with generic libraries, an
>iterative process of document and code is often unavoidable. Still, I
>have my concerns about encouraging "after-the-fact" specifications, and

>about the possibility of implementation details leaking into the
>documentation when the latter is automatically generated from source
>In at least one case, automatically-generated documentation can't avoid
>revealing implementation details that should, perhaps, be hidden from
>user. For example, suppose a define a function f that takes arguments
>type foo_t. Does it matter to the user whether the signature of f is
>"void f(foo_t)" or "void f(foo_t const &)"? As the implementor of f, I

>might like to have the freedom to switch between the two signatures
>depending on whether or not I need a copy of the argument.
>Unsubscribe & other changes:

Unsubscribe & other changes:

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