[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-core-devel
Subject:    Re: kdelibs API documentation (was Re: Moving ThreadWeaver to kdelibs)
From:       Kevin Krammer <kevin.krammer () gmx ! at>
Date:       2005-09-15 18:32:34
Message-ID: 200509152032.39885.kevin.krammer () gmx ! at
[Download RAW message or body]


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@gmx.at>
Qt/KDE Developer, Debian User
Moderator: www.mrunix.de (German), www.qtforum.org

[Attachment #3 (application/pgp-signature)]

[prev in list] [next in list] [prev in thread] [next in thread]