Review Request: Make the api docs more readable

[Sebastian Trueg]

> 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.
> 
> Andreas Pakulat wrote:
>     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

Ok, then I suppose order by declaration is off the table as we have two votes against it.
What about the left alignment? I think this is really important as the jusitified layout is a mess with all those method names that cannot properly be broken down.


- Sebastian


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