API docs; functional or pretty?

[Adriaan de Groot]

On Sunday 25 June 2006 15:31, Dominik Haumann wrote:
> My aim also was't to stress the appearance too much, I still think we
> simply need to write very good api documentation. That's why I mentioned
> the stuff about grouping etc again.

Yes, writing better docs with good overviews, meaningful mainpages and 
grouping classes together to give a better (finer-grained that per-directory) 
logical structure to the API is an important issue. I'm a big fan of 
@ingroup, @{, @section and all that, but I'm afraid the biggest problem with 
writing good APIDOX is that the people who know the API need to write them. I 
know you, Dominik, have done good work in the past adding APIDOX, but we 
can't expect you to write the book on KDE's APIs all by yourself.

I ought to -- or someone -- add a little blurb to the APIDOX HOWTO (it's 
rather dated by now with its KDE3 centered instructions -- I think KDE 3 
APIDOX are dead now) about sectioning. It's on developer.kde.org so open to 
everyone to improve.

[ade]