[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:       Brad Hards <bradh () frogmouth ! net>
Date:       2005-09-14 12:27:32
Message-ID: 200509142227.39194.bradh () frogmouth ! net
[Download RAW message or body]


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. 

See 
http://websvn.kde.org/trunk/kdesupport/qca/examples/examples.doco?rev=419358&view=markup
for how simple it can get.

The advantage of that sort of approach (rather than cutting and pasting into 
\code blocks) is that if the examples get out of sync with the code, the 
compiler can tell us.

Brad

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

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