[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-pim
Subject:    [Kde-pim] API docs online -- fixing them
From:       a.degroot () science ! ru ! nl
Date:       2005-02-21 23:40:17
Message-ID: Pine.GSO.4.44.0502212326180.24885-100000 () odin ! cs ! kun ! nl
[Download RAW message or body]

The API docs are online (still), and now updated to include KPilot;
there's also better navigation if you want to just browse around. With the
freeze coming up, and everyone wondering what to do, I think it's time to
get medieval on our API docs. Having better docs means that we can bring
new devs up to speed faster, easier (think of Keith or Matt). There are
several steps to be taken:

1) Take a look at the existing docs,
http://www.cs.ru.nl/~adridg/pim.kde.org/apidocs/ ; browse to your favorite
bit (ie. kpilot/lib, or libemailfunctions). There are (nearly) always two
menus off to the left -- one for the currently selected part of PIM, and
one titled API Docs listing all the parts of PIM that have dox.

2) Note how you get just a boring page with a table of links -- no
indication at _all_ about what this chunk of code is about. There is no
major difference between what you see when you hit the dox for KMail vs.
the dox for KonsoleKalendar, although the apps are slightly different in
structure and intent. Now hit the Karm dox. Compare. This is job [a].

3) Go to the libemailfunctions dox. Notice that it has a very brief
mainpage (job [a]); Matt will be fixing that up. Notice also that it has
an entry "File List" in the menu. This is job [b].

4) Now go to the KitchenSync dox, choose Namespace List. That's rather odd
documentation for the namespace, don't you think? It really belongs with
the first class _inside_ the namespace. And if you go looking for the
class that is mentioned there you see that it isn't documented at all.
What's weird is that the source file kitchensync/libkonnector2/idhelper.h
_has_ documentation. This is job [c].


I hope you've enjoyed the little tour around the docs and are wondering
what the different jobs entail. Well:

[a] Every directory _may_ have a file Mainpage.dox that describes what's
going on and why. It is just a normally formatted doxygen comment with a
@mainpage blabla tag at the start. This is your chance to give a
high-level description of the part of PIM you're concerned with; a brief
architectural overview, say. No need to link to anything in particular,
the menu on the left gives access to everything. If you mention functions,
namespaces, classes in the mainpage text, links are automatically
generated. Karm's mainpage is pretty good in this respect.

So: write a high level overview of your part of PIM, and stick it in
mainpage.dox.

[b] (This one is kinda drudgework) In files you want listed in the File
List (and really, that's all of them), add a comment /** @file */ after
the copyright header. That's all.

[c] Files need to be documented from the outside in, so you (sortof) need
a /** @file */ header (job [b]) and then a /** */ comment just in front of
a namespace declaration, and then a /** */ comment just in front of a
class, and then a /** */ comment in front of methods. If you leave one out
(say, the class comment) then the 'disconnected' bits are left out
entirely (which is why you don't see the docs for methods of class
KonnectorUIDHelper, since the namespace is doxied but the class itself
isn't. This job involves looking at header files and making sure that at
least the outer parts -- class or namespace -- are doxied, so that all the
namespaces and most of the classes show up in the dox.

Just take a look at some bits you know -- chances are, you'll find lots of
methods documented, but not showing up because there's surrounding
structure without a comment. Please add them, so our total coverage goes
up a lot.




Now, about process -- during the total freeze, all commits must be
approved. I think if you send patches to me I can update the online dox
quickly (except during FOSDEM this weekend), and we can do one huge
comments-only-commit sometime during the freeze.

Of course, you may want to work on critical data-loss bugs in PIM instead.
There's still enough of them.

-- 
As of September 1st, 2004, the University of Nijmegen will _still_ be the
University of Nijmegen, but with a different nonsensical adjective in front.
    Reach me at groot@kde.org instead. GPG FEA2 A3FE

_______________________________________________
kde-pim mailing list
kde-pim@kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
kde-pim home page at http://pim.kde.org/
[prev in list] [next in list] [prev in thread] [next in thread]