Review Request: Make the api docs more readable

[Sebastian Trueg]

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

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/kde.css 1047248
  trunk/KDE/kdelibs/doc/common/Doxyfile.global 1047248

Diff: http://reviewboard.kde.org/r/2132/diff


Testing
-------


Thanks,

Sebastian

[Sebastian Trueg]

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

(Updated 2009-11-10 23:58:03.193380)


Review request for kdelibs.


Changes
-------

Fixed size of contents.


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 (updated)
-----

  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

[Sebastian Trueg]

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

(Updated 2009-11-11 00:25:34.669534)


Review request for kdelibs.


Changes
-------

Ok, one more: no more justified contents. Left aligned text is way more readable.


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 (updated)
-----

  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

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


Now I prefer "fluid layout" instead of fixed-width layouts on the Web myself.  But I would caution against
declaring that using 100% of available width is more readable.  After all, centuries of typography seem to indicate that people have an easier time reading somewhat narrower text (e.g. the columnar layout of magazines, newspapers, journals, etc.)

At the same time, computer typography is /not/ the same as print typography.  I guess the point I'm trying to make is that is may still make sense to have some kind of max width if CSS supports (i.e. I see a commented-out max-width property), perhaps set to 12-15 cm or so.  Or make the text size a bit bigger to compensate for the wider lines.

I understand this is very bikesheddable (and that the user can simply resize the window...).  I'll try the CSS changes on my widescreen monitor to see if it looks crazy or not.

- Michael


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

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


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.


- Aaron


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

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


OK, having tried it out, I think full width actually looks fine for the most part, general class documentation seems easily readable (as long as it has code samples interspersed or something else to break up the paragraphs).

I would still prefer the actual member function implementations to have a constrained max width (although 15 cm was far too little).  Looking at the generated sources, something like this worked for me in the kde.css:

.memitem {
  max-width: 21cm;
}

One technical hiccup is that you attempt to comment out the max-width declarations in the file, but # isn't a CSS comment character (at least according to vim syntax highlighting ;).  /* foo */ definitely works.

Really I'm glad to see any work done on this though, we could make the API documentation a *lot* better-looking.

But perhaps try the max-width on the member function docs and see what you think, I think it's better but that could just be me.

- Michael


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

[Sebastian Trueg]

> On 2009-11-11 01:43:26, Michael Pyne wrote:
> > OK, having tried it out, I think full width actually looks fine for the most part, general class documentation seems easily readable (as long as it has code samples interspersed or something else to break up the paragraphs).
> >
> > I would still prefer the actual member function implementations to have a constrained max width (although 15 cm was far too little).  Looking at the generated sources, something like this worked for me in the kde.css:
> >
> > .memitem {
> >   max-width: 21cm;
> > }
> >
> > One technical hiccup is that you attempt to comment out the max-width declarations in the file, but # isn't a CSS comment character (at least according to vim syntax highlighting ;).  /* foo */ definitely works.
> >
> > Really I'm glad to see any work done on this though, we could make the API documentation a *lot* better-looking.
> >
> > But perhaps try the max-width on the member function docs and see what you think, I think it's better but that could just be me.

I am totally fine with using a max-width on memitems. Still is very readable.


- Sebastian


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


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

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

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.


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

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

> On 2009-11-11 01:43:26, Michael Pyne wrote:
> > OK, having tried it out, I think full width actually looks fine for the most part, general class documentation seems easily readable (as long as it has code samples interspersed or something else to break up the paragraphs).
> >
> > I would still prefer the actual member function implementations to have a constrained max width (although 15 cm was far too little).  Looking at the generated sources, something like this worked for me in the kde.css:
> >
> > .memitem {
> >   max-width: 21cm;
> > }
> >
> > One technical hiccup is that you attempt to comment out the max-width declarations in the file, but # isn't a CSS comment character (at least according to vim syntax highlighting ;).  /* foo */ definitely works.
> >
> > Really I'm glad to see any work done on this though, we could make the API documentation a *lot* better-looking.
> >
> > But perhaps try the max-width on the member function docs and see what you think, I think it's better but that could just be me.
>
> Sebastian Trueg wrote:
>     I am totally fine with using a max-width on memitems. Still is very readable.

I suggest to use a different unit instead of cm. cm means a relatively fixed width on all monitors, something that scales with the font like "em" would probably be better so people using large fonts still get to see most of the text instead of having it cut after the return-value :) Would of course need some more experimenting wrt. how "many" ems to use.


- Andreas


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


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

Am Mittwoch 11 November 2009 10:02:32 schrieb Andreas Pakulat:
> I suggest to use a different unit instead of cm. cm means a relatively
>  fixed width on all monitors, something that scales with the font like "em"
>  would probably be better so people using large fonts still get to see most
>  of the text instead of having it cut after the return-value :) Would of
>  course need some more experimenting wrt. how "many" ems to use.

For the text width, 40em is a good rule of thumb among typographs.

Greetings
Stefan

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

> 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
>
> Sebastian Trueg wrote:
>     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.

Hmm, one problem with left-aligned is that you can't easily see where the function name starts and the return-value stops. In Qt api docs thats easy because the return value is no link (which again I hate in Qt API as I often want to jump to the class without looking at the method description). I'll try to actually test it later tonight, but right now I think I'm against that.


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