Review Request: Make the api docs more readable

[Andreas Pakulat]

> On 2009-11-11 01:07:04, Aaron Seigo wrote:
> > non-alphabetical makes it even more difficult to find methods in many cases; personally, i'd like to see our apidox as close to Qt's as possible for consistency's sake.
> > 
> > when i look at http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/classPlasma_1_1Corona.html for instance, i have the ctor at the top of the public member functions (good!) but slots and signals are above that which doesn't make a whole lot of sense.
> >
> 
> Sebastian Trueg wrote:
>     If a class has lots of methods and you need to find a specific one you need to search anyway. But if you do not know the class and the names of its members it makes way more sense to have them ordered by type. And by type I mean functionality grouping like: getter and setter, then tool methods and finally fancy conversions and such.

Quite frankly, I think the API docs are used way more often to lookup a method (to read its description) than people just "browsing through". After all "browsing through" is usually also caused by the need to find something to do a given task. Where again one might have some idea about naming of classes/methods and hence an alphabetical order is much better.

I completely object ordering methods as in the declaration, they should be sorted alphabetically. I'm still using the Qt3 api docs where the sorting was "random" and its a complete mess to search for a function there. The Qt4 api docs are million times better


- Andreas


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
http://reviewboard.kde.org/r/2132/#review3009
-----------------------------------------------------------


On 2009-11-11 00:25:34, Sebastian Trueg wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> http://reviewboard.kde.org/r/2132/
> -----------------------------------------------------------
> 
> (Updated 2009-11-11 00:25:34)
> 
> 
> Review request for kdelibs.
> 
> 
> Summary
> -------
> 
> There have always been a few things that annoyed me about the KDE api docs. This patch fixes two of them:
> 1. Members are now sorted according to declaration order. This makes way more sense than alphabetical order since most if not all developers try to put the members in a proper order anyway and having to find constructors somewhere in between all other members is just annoying.
> 2. Use the full width of the browser window. API docs need to be readable and line-breaks are never a goo thing here. Thus, using all the space we have is a must.
> 
> 
> Diffs
> -----
> 
>   trunk/KDE/kdelibs/doc/common/Doxyfile.global 1047248 
>   trunk/KDE/kdelibs/doc/common/kde.css 1047248 
> 
> Diff: http://reviewboard.kde.org/r/2132/diff
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Sebastian
> 
>