Review Request: Make the api docs more readable

Andreas Pakulat apaku at gmx.de
Wed Nov 11 09:02:32 GMT 2009



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





More information about the kde-core-devel mailing list