[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:       Benjamin Meyer <ben () meyerhome ! net>
Date:       2005-09-14 10:48:05
Message-ID: 200509140706.06344.ben () meyerhome ! net
[Download RAW message or body]


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 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?

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.  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()

-Benjamin Meyer

-- 
aka icefox
Public Key: http://www.icefox.net/public_key.asc

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

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