RE: [boost] Re: Reference documentation

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

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.

/David

-----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
want  
>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
code.
>
>In at least one case, automatically-generated documentation can't avoid
>revealing implementation details that should, perhaps, be hidden from
the  
>user.  For example, suppose a define a function f that takes arguments
of  
>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:
http://lists.boost.org/mailman/listinfo.cgi/boost

_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost