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

[Dominik Haumann]

On Wednesday 14 September 2005 13:06, Benjamin Meyer wrote:
> I 100% agree.  They are very valuable for developers to explore classes
> and look up documentation.  When looking for something even if they don't
> pick the correct function there is a good chance that what they want is
> in the related functions.  Also typically when reading docs seeing the
> related functions help you realize the classes functionality.
>
> The hard thing would be coming up with a policy that makes sense.  Maybe
> something like:
>
> When possible include references to other functions with @see.
> @see provides a easy way for developers to explore the documentation.
> Functions that are part of a get/set pair should reference each other. 
This is especially important for reimplemented functions as the setter (or 
getter) then is in the superclass (and such invisible, i.e. not listed in 
the current documentation page).

> You should also reference functions that the developer might want to do
> rather then using this function.  For example copy() could have  @see
> operator= Another example would be a function that returns -1 if the 
> object is null. That function should include a reference to isNull()
I agree.

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.


Important for all the documentation is to not write "bla bla". The docs must 
be to the point ie. contain valuable information which can be very hard to 
do.

Cheers,
-- 
Dominik