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

List:       kde-pim
Subject:    [Kde-pim] Keeping apidox up-to-date
From:       Adriaan de Groot <groot () kde ! org>
Date:       2005-06-27 1:02:46
Message-ID: 200506270302.46886.groot () kde ! org
[Download RAW message or body]

The apidox for KDE PIM are now generated semi-regularly from the SVN trunk 
sources, and are visible at 
http://developer.kde.org/documentation/library/cvs-api/kdepim-apidocs/ -- 
that's the "API docs" link under Development->Architecture on the PIM 
website.

Allen and I are the watchdogs over the dox; we get regular reports from the 
dox generation. To keep our workload low, (in terms of fixing dox all the 
time -- we also have libs and base to cover), I'd like to point out some 
guidelines and give some tips wrt. the dox in PIM code (Thorsten, listen 
up!).

The official dox guide for KDE is at 
http://developer.kde.org/policies/documentationpolicy.html . This is fairly 
library-oriented. PIM is unusual in that its applications also have extensive 
dox -- I think that's a good thing, since it lowers the barriers to entry for 
new developers as well. The dox guide is somewhat grumpy in tone, but most of 
it is good advice. I don't think rule #10 needs to be followed religiously, 
though:

	Run "make apidox" before you commit any code.

Not everyone has doxygen installed, not everyone needs to be able to do that. 
Apidox are built elsewhere all the time, and Allen and I get to see the 
results, so any problems that result will be caught eventually. But let's try 
to prevent errors, shall wel?

1) Use doxygen-style comments (that's those that start /** ) _only_ for actual 
dox. Don't surround other things like licenses with them. Carsten put /** 
around the GPL header in several KMail files, with the result that the dox 
for bits and pieces of KMail was suddenly the text of the GPL header.Oops. 
Took a fair bit of effort to track down, too, and remove the offending extra 
*.

2) When you add a new method to a class, give it dox. Even when the method is 
private. Remember, low barrier to entry.

3) Dox are case-sensitive. Case in point:

	karm/karmdcopiface.h:38 Warning: argument `taskname' of command @param is not 
found in the argument list of KarmDCOPIface::addTask(const QString &taskName)

(This is an otherwise correct and useful dox entry added by Thorsten recently, 
just with a typo. These get fixed automagically by Allen & me.)

4) When defining a subclass and overriding methods, remember to name arguments 
to the method the same as they were in the method in the superclass:

	karm/mainwindow.h:69 Warning: argument `taskId' of command @param is not 
found in the argument list of MainWindow::bookTime(const QString &uid, const 
QString &datetime, long minutes) inherited from member bookTime at line 49 in 
file /mnt/src/kde-HEAD/kdepim/karm/karmdcopiface.h

(In this case, the superclass has the method definition bookTime( const 
QString &taskId ... ) which is just subtly different. Again, these get fixed 
automagically by Allen and me if we can figure them out.)



Now, how can you check your dox? If you have doxygen installed (preferably 
version 1.4.1 -- 1.4.3 does some things differently and throws different 
warnings), "make apidox" in a configured build directory will build the 
apidox for the current directory, or for all of KDE PIM if you are in the 
top-level. That's one way.

If you don't have a build directory, or don't want to run make just now (say 
because you know lots of Makefile.am's have changed, or acinclude.m4.in has 
changed and you don't want to sit through the whole configure process again), 
you can run the dox generating script by hand (again, assuming you have 
doxygen installed). Take a look at the command run by "make apidocs", it's 
easy enough to figure out -- doxygen.sh takes the top-srcdir as argument and 
possibly a subdir to build as well, so something like sh admin/doxygen.sh . 
karm will rebuild the karm dox when you're in the top of a PIM source 
checkout.



Your doxide tavern,
[ade]


-- 
These are your friends - Adem
    GPG: FEA2 A3FE Adriaan de Groot
_______________________________________________
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]