From kde-core-devel  Wed Sep 14 08:27:58 2005
From: Dominik Haumann <dhdev () gmx ! de>
Date: Wed, 14 Sep 2005 08:27:58 +0000
To: kde-core-devel
Subject: kdelibs API documentation (was Re: Moving ThreadWeaver to kdelibs)
Message-Id: <200509141027.58868.dhdev () gmx ! de>
X-MARC-Message: https://marc.info/?l=kde-core-devel&m=112668771814334

On Wednesday 14 September 2005 01:26, Aaron J. Seigo wrote:
> does anyone think this is too great a burdon to put on new additions to
> kdelibs? would anyone be willing to join me in writing such documentation
> for existing classes for kde4?
Yes, count me in :)

> once things calm down a bit in kdelibs,
I'm just waiting for this to happen... but it seems to take some time.

Besides the why/when/how documentation I'd also like to propose to add more 
function references (@see) in the documentation. Trolltech does this for a 
long time already (see assistant 3.x), example:
  QString QString::right ( uint len ) const 
  [...]
  See also left(), mid(), and isEmpty().

I often feel that such references are really missing in KDE documentation.
Examples:
  void KPushButton::setText();
  missing reference to: @see text()

  QColor KColorButton::color();
  missing references to: @see setColor() defaultColor()

Such references are extremely helpful for developers who do not know the API 
very well, _especially_ if corresponding functions are (hidden) in 
inherited classes. All kdelibs should have this @see-references, it should 
be a policy, too.

Any comments?

-- 
Dominik