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

List:       kde-core-devel
Subject:    kdelibs API documentation (was Re: Moving ThreadWeaver to kdelibs)
From:       Dominik Haumann <dhdev () gmx ! de>
Date:       2005-09-14 8:27:58
Message-ID: 200509141027.58868.dhdev () gmx ! de
[Download RAW message or body]

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
[prev in list] [next in list] [prev in thread] [next in thread]