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

[Aaron J. Seigo]

On Wednesday 14 September 2005 05:56, Adriaan de Groot wrote:
> On Wednesday 14 September 2005 10:27, Dominik Haumann wrote:
> > On Wednesday 14 September 2005 01:26, Aaron J. Seigo wrote:
> 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 wasn't talking about API documentation.

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

i'll leave this to someone else. i don't have time to document every nook and 
cranny in kde. i do have the time to write probably one overview piece every 
week or so.

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

again, while this would be great to see happen, i don't have the time nor the 
inclination to do this. you'll have to find someone else to help out here. if 
i spent my time doing API docu or writing gobs of HOWTO docu for 3.5, i would 
end up sacrificing something else out of my task list. so i'm focussing on 
high level docu for kde4, which also happens to give me a few months to 
concentrate on things i need to be doing right now.

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

this is, in part, why we're forming bodies to do oversight of certain areas of 
KDE. once they are in place, i'd suggest taking advantage of them.

-- 
Aaron J. Seigo
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

Full time KDE developer sponsored by Trolltech (http://www.trolltech.com)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20050914/105b41f6/attachment.sig>