API docs; functional or pretty?

[Matt Rogers]

On Thursday 22 June 2006 13:00, Thomas Zander wrote:
> Hi all.
>
> I strongly believe in having good tools to make the job easier and get
> better results. For that reason I've been focussing on APIDocs recently
> since after the admin dir went RIP koffice didn't have any docs anymore.
>
> I ended up with a script that solves several problems I've been having in
> KDEs docs.  I listed some important ones in my blog[1] but overall goal
> is to move from:
> a) pretty docs that fit in the kde sites to ones functional for reference;

they should be both pretty and functional. Documentation that is hard to read 
(or search through) will not be used. Frankly, the KOffice docs look like as 
presented in [3] look like crap, and I wouldn't use them if they looked like 
that.

> b) package based to class based searching.
> Most devs don't know if a class comes from kdecore or kdeui or whatever,
> so they end up clicking and searching all. Moreover since the classes
> without docs don't show up anywhere it tends to be a hit and miss.

with a few exceptions, using "kde: ClassName" works just fine for me, so I 
don't have a good grasp of what you mean here. In most cases I don't need to 
know that a class is in kdecore or kdeui.

> c) Better inter-project links.  I can now see (and click on) a parent
> class even if its in another lib.
>

that is nice.

> And last, but not least,  a patch I wrote for doxygen to allow KDELibs to
> have all signals properly listed again since we tend to have Q_SIGNAL in
> the header files. see [2]
>

This patch is fine. It should be submitted to the doxygen folks.

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

No, the current state is not keeping me from using them. What was keeping me 
from using them (until the EBN server went down) was that the docs on dev.k.o 
were not as current as those on the EBN. Now that that problem is fixed, it's 
fine. I can usually type "kde: ClassName" into the Run Command dialog and get 
what I need.

I don't think the way you've done the API docs in [3] is better. I think it's 
worse actually. Why? Because I have to search for a particular class myself 
in this long list of other classes that I don't care about. I think the 
easiest way to solve this problem is to offer htdig searches if htdig is 
installed. I believe doxygen will do this already since around version 1.4.x. 
You could also go with the class mapper approach as used on dev.k.o as 
another, perhaps easier option.


> What can we do with the problem Adriaan put forth that as long as the docs
> don't look and behave like the kde - site (which IMO makes them unusable)
> we can't have them on developer.kde.org?
>

Come up with something better that makes them both pretty and functional. Do I 
think the current way of doing things a la dev.k.o is good? Perhaps not, but 
I'm not sure.
--
Matt