kdelibs API documentation (was Re: Moving ThreadWeaver to kdelibs)

[Adriaan de Groot]

On Wednesday 14 September 2005 10:27, 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?

Is there any reason to wait? As you can see on 
http://www.englishbreakfastnetwork.org/ , for kdelibs4 there's a non-zero 
number of members of existing classes left undocumented. I'll be the first to 
admit that the Doxygen settings used by me for kdelibs4 right now are a 
little 'shotgun', so there's a fair amount of errors that are not really 
interesting -- but at the same time there's just _gobs_ of API methods not 
documented, and a fair number of methods whose parameters are not properly 
done either.

So there's a lot of micro-scale improvements that can be made. This is 
separate from the macro-scale improvements of having good overview 
documentation.

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

Don't forget there's also KDE 3.5 which has an API which isn't documented all 
proper either (though _I'm_ not putting any effort into it anymore, since I 
don't believe dox fixes will be forward-ported). And there are various 
applications that have weird-ass dox as well. You might want to borrow a 
blunt axe and talk to some KOffice developers about the meaning of 'int 
flags'.

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

You don't necessarily have to use @see, you can also refer to the method in 
running text -- we do not have a styleguide one way or the other, so you 
could write

	This method returns the rightmost @p len characters, similar
	to how left() and mid() return characters out of the string.

Though in this particular example, @see makes much more sense.

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

There's a policy http://developer.kde.org/policies/documentationpolicy.php , 
to which I added points 11 and 12 which aren't really policy-worthy since 
they're just (11) some doxygen hints, which if you ignore them will lead you 
to break policy item (10), and (12) is similar. They belong in the dox howto. 
I sort of intend to remove those two policy items again, since they're 
irrelevant.

What _is_ relevant is how we arrived at the apidox policy, how (if) it is 
enforced, and what it takes to change such a policy. If the policy is 'random 
rules someone pulled out of his arse', then changing it is easy but it's not 
exactly relevant; if the policy is something that was decided upon in a more 
reputable fashion, then we can't just go about adding stuff to it (otherwise 
I would have banned @ref and the use of # long ago).



-- 
These are your friends - Adem
    GPG: FEA2 A3FE Adriaan de Groot