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

[Dominik Haumann]

On Thursday 15 September 2005 14:55, Kevin Krammer wrote:
> On Wednesday 14 September 2005 14:27, Brad Hards wrote:
> > Non-abstract classes should have compilable examples. Currently what we
> > have in tests/ is a combination of unit tests and examples. If we move
> > the examples out into an examples/ directory, we can then link them
> > into the API docs, as is done for QCA.
>
> 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?
For example the KTextInterface. Usually we describe what the function does 
(for the user), as the implementor will have to provide exactly this 
functionality. Additional comments can be added with
  @note Implementations have to make sure bla...... or such

> Or separately in a different file and link to it?
I'd say in the same file. It's easier to maintain, as if you change a 
description you can change the notes immediately, too, without having to 
look into other files (which then often isn't done at all).

-- 
Dominik