API docs; functional or pretty?

[Andreas Pakulat]

On 22.06.06 20:00:23, Thomas Zander wrote:
> I'd like to get feedback from you guys to see if this can be used for 
> broader consumption. Is the current state of online docs stopping you 
> from using them as a good tool? You think the ones online for koffice 
> better[3] ?

I'm not a kde developer (well, I do develop kde apps, but I'm not
"registred" ;-), however I'd like to make a comment about this from a
"using the api docs on a not-so-regular" perspective. I also didn't
read your blog (don't have the time right now).

I compared the KoDocument class between your new version from [3]
and the one on developer.kde.org. And while your version is lacking the
inheritance graph - which I think is really nice so you see within a
second which classes this class comes from, rather than having to click
yourself up the inheritance hierarchy - I think it gives the developer
more information with less scrolling/reading to do. Especially that the
several items now have the first sentence of documentation within the
overview part is nice. 

Also separarting each function/type/whatever with a very slight line can
help to read the docs faster and doesn't stress the eyes so much.
Especially on multi-line-function-paramter-lists.  Also finding a
specific class on the left-frame is much easier, I couldn't even find
KoDocument with kde: KoDocument.

Your version looks a bit like the Qt class documentation (not so much
color-wise, but layout-wise) and I think that documentation from TT is
very good. I often don't even need to read the full description of a
method or class, especially for those that I only use seldom and thus
forget the proper naming... 

So much for my 2¢.

Andreas

-- 
Truth will out this morning.  (Which may really mess things up.)