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

[Kevin Krammer]

On Thursday 15 September 2005 15:20, Dominik Haumann wrote:
> On Thursday 15 September 2005 14:55, Kevin Krammer wrote:

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

True.
I just wanted to bring it up for discussion, so we can possibly agree on a 
certain style.

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

I favor this as well.

Cheers,
Kevin

-- 
Kevin Krammer <kevin.krammer at gmx.at>
Qt/KDE Developer, Debian User
Moderator: www.mrunix.de (German), www.qtforum.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20050915/b3993233/attachment.sig>