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

[Kevin Krammer]

On Wednesday 14 September 2005 14:27, Brad Hards wrote:
> On Wednesday 14 September 2005 21:51 pm, Dominik Haumann wrote:
> > Summary so far:
> > 0. A class provides a detailed description, namely (as Aaron said)
> >    1  para  Introduction and Overview
> >    1+ paras Why (might be possible to be included in the introduction)
> >    2+ paras How to use it in the common case, with short/accurate
> > examples 0+ paras on common gotchas or extra details
> >
> > 1. setter/getter must reference each other
> >    eg. setText/text
> >
> > 2. signals must reference setter/getter
> >    eg. for signal modifiedChanged(): @see isModified()
> >    eg. for signal valueChanged(): @see value()
> >
> > 3. additionally add references that make sense
> >
> > 4. Another addition: Signals must have a 100% accurate description of
> >    when they are emitted. I just had a quick look, many signals do that
> >    already :) Qt usually uses the famous "This signal is emitted
> >    whenever ..." throughout all the documentation, it is very consistent
> >    and reads nicely. I think we should copy it.
>
> 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?

/**
* Docs about usage
* Implementor notes: ...
*
* @param
* @return
*
*/

or

/**
* Docs about usage
* @param
* @return
*
* Implementor notes: ...
*/

Or separately in a different file and link to it?

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/432d239b/attachment.sig>