API docs; functional or pretty?

[Matt Rogers]

On Thursday 22 June 2006 13:40, Frans Englich wrote:
> 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.
>

ugh, yet another overengineered xml thingie. (from a perspective of somebody 
who's dabbled in docbook very very little.)


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

So how is converting from header -> xml (via doxygen) -> docbook -> html 
better than the current header -> html (via doxygen)?

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

Yeah, get over it. 

> 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 sure you'd disagree, but I think an all docbook dev.k.o would be even more 
broken.

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