kdelibs API documentation (was Re: Moving ThreadWeaver to kdelibs)

[Adriaan de Groot]

On Thursday 15 September 2005 14:55, Kevin Krammer wrote:
> On the matter of abstract classes:
> abstract classes or interfaces have two groups of API doc readers. The
> developers who use the interface and the developers who implement it.
>
> In my experience docs that are sufficient for the first group often miss
> things the implementors are interested in.
> Should an interface author include both kind of information in the API docs
> in one block, or separated?

You can also use grouping, for instance you can do

/** @defgroup implementors Notes for Implementations */

/** Do something cool. */

void coolness();

/** @addtogroup implementors

These are the notes about a method relevant for implementors; they should come
after the method definition and @em before the dox for the next method.
To implement coolness, you need a baseball cap.
*/

I'm not entirely sure how these come out; alternatively, subpaging may be an 
option -- I can figure that out for you if you like and write up a suggested 
dox style for interfaces.


-- 
These are your friends - Adem
    GPG: FEA2 A3FE Adriaan de Groot