API docs; functional or pretty?

[Frans Englich]

On Thursday 22 June 2006 18: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]

Another recent blog on Doxygen:

http://englich.wordpress.com/2006/06/21/doxygen-galore/

> but overall goal 
> is to move from:
> a) pretty docs that fit in the kde sites to ones functional for reference;
> 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.
> c) Better inter-project links.  I can now see (and click on) a parent
> class even if its in another lib.
>
> 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]

Didn't this work for you?

PREDEFINED = KDECORE_EXPORT="" \
        KDEUI_EXPORT="" \
        KDEFX_EXPORT="" \
        KDE_DEPRECATED="" \
        Q_OS_UNIX="" \
        Q_SLOTS="slots" \
        Q_SIGNALS="signals"

That's what doc/api/Doxyfile.local contains.

Nevertheless, you should consider attaching your patch to:
http://bugzilla.gnome.org/show_bug.cgi?id=338475

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

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

I vaguely recall having bounced DKO with Adriaan in private mail. I have this 
idea of fully integrating all documentation concerning KDE, API 
documentation, possibly user manuals, guidelines(HIG, HOWTOs, etc), into the 
strongest and common denominator: Docbook.

Doxygen can output XML, and there's a project that converts Doxygen into 
Docbook(I have a link somewhere..).

By having everything in Docbook, we can link across everything(say, from the 
HIG to a particular enum in a class), index across everything, and export to 
whatever format you like, etc, etc. Of course, considering I'm an XML geek, 
I'm having trouble breathing while describing that.

This is a huge project, and it would require lots of work, but I think it is a 
good way to go. I think "fixing" DKO is tremendously important for KDE.

One problem is that DKO needs fixing. And I'm not talking about the overhaul 
it gets every second month where half of it breaks, half of the files are 
moved around breaking all links, some random personal style is applied, and 
so on.

I'm talking about planning before implementation, usability analysis, document 
how to maintain the site, deploying a URI policy[1] to ensure persistence, 
deploying validation mechanisms(404 URIs, CSS/XHTML validness), and so on.


Cheers,

		Frans

1. For example, that file prefixes such as 'html', 'php', aren't exposed in 
URIs, since it's an implememntation detail.