From kde-core-devel  Wed Sep 14 10:48:05 2005
From: Benjamin Meyer <ben () meyerhome ! net>
Date: Wed, 14 Sep 2005 10:48:05 +0000
To: kde-core-devel
Subject: Re: kdelibs API documentation (was Re: Moving ThreadWeaver to kdelibs)
Message-Id: <200509140706.06344.ben () meyerhome ! net>
X-MARC-Message: https://marc.info/?l=kde-core-devel&m=112669488502661
MIME-Version: 1
Content-Type: multipart/mixed; boundary="--nextPart1785947.4ptIDUEAIN"

--nextPart1785947.4ptIDUEAIN
Content-Type: text/plain;
  charset="iso-8859-6"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

On Wednesday 14 September 2005 4:27 am, Dominik Haumann wrote:
> 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 documentati=
on
> > 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 mo=
re
> 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?

I 100% agree.  They are very valuable for developers to explore classes and=
=20
look up documentation.  When looking for something even if they don't pick=
=20
the correct function there is a good chance that what they want is in the=20
related functions.  Also typically when reading docs seeing the related=20
functions help you realize the classes functionality.

The hard thing would be coming up with a policy that makes sense.  Maybe=20
something like:

When possible include references to other functions with @see.
@see provides a easy way for developers to explore the documentation.
=46unctions that are part of a get/set pair should reference each other.  Y=
ou=20
should also reference functions that the developer might want to do rather=
=20
then using this function.  For example copy() could have  @see operator=3D =
=20
Another example would be a function that returns -1 if the object is null. =
=20
That function should include a reference to isNull()

=2DBenjamin Meyer

=2D-=20
aka icefox
Public Key: http://www.icefox.net/public_key.asc

--nextPart1785947.4ptIDUEAIN
Content-Type: application/pgp-signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQBDKAQe1rZ3LTw38vIRAntaAJ4+UD8K25cgR6nVL3CwbR0Y46cgQwCeOiOj
MrZACoW2F/SOcSQCchVdtg0=
=0Mgb
-----END PGP SIGNATURE-----

--nextPart1785947.4ptIDUEAIN--