API docs; functional or pretty?

[Dominik Haumann]

On Thursday 22 June 2006 20: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; 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]
>
> 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?
>
> Thanks!
>
>
> 1) http://lists.kde.org/?l=kde-core-devel&m=112954041028124&w=2
> 2) http://members.home.nl/zander/signalsSlots.diff
> 3) http://www.koffice.org/developer/apidocs/

This is my *very personal* feeling about the current online api reference:
- it is **very** important, think: It's about gaining new developers
- I actually never use the "APIDox" bar on the left, I'd like to see
  it vanish (*)
- The box above "APIDox" which includes "Mainpage", "Namespace List", etc.
  should be horizontally aligned on the top.

I have to say though, that the link above on (3) is not necessarily helpful,
as it simply clutters *all* classes in a frame - does this really help?

(*) We should start to heavily use groups instead, see for example [1]. Also
every module (kdeui, kdecore...) should have a usable MainPage, I tried this
for the KTextEditor interfaces on [2].
Example of groups: Aaron's kdelibs_kconfig branch contains all new kconfig*
stuff, every touched class should have a \ingroup kconfig. Then the group
kconfig itself should give a detailed overview over how the config system
works + further hints, so that a newbe understands how and what he should
use when. (Btw: This documentation takes a lot of time, it's not written in
two hours, as you first have to understand everything yourself (go Aaron! go!
:) ) It also should contain _integrated_ howtos/code peaces, no links to
extern pages.

Next, I think it would be very cool to have a KDE equivalent for qtAssistant.
I know there is KDevAssistant, but it's somehow not so straightforward to use.
Best would be to make qtAssistant accept our doxygen generated tag files as
input. Btw: alt+f2: kde:ClassName really rocks :)

That said: Yes, the appearance is important (it should look professional, the
mentioned link at (3) does not imho), but the content is even more important.

We had similar discussions at
- http://lists.kde.org/?l=kde-core-devel&m=112668771814334&w=2 whole thread!
- http://lists.kde.org/?l=kde-core-devel&m=112954041028124&w=2 oops, same as link (1) ;)

--
Dominik

[1] http://developer.kde.org/documentation/library/cvs-api/kdelibs-apidocs/interfaces/ktexteditor/html/group__kte__group__doc__extensions.html
[2] http://developer.kde.org/documentation/library/cvs-api/kdelibs-apidocs/interfaces/ktexteditor/html/index.html