[kplato] Writing APIDox proposal

[Raphael Langerhorst]

Am Freitag, 31. März 2006 11:19 schrieb Dag Andersen:
> On Thursday 30 March 2006 20:55, Pierre-Andre Galmes wrote:
> > Hello,
> >
> > last questions before starting :
> >
> > - Which Koffice version should I work on ? I downloaded the
> > snapshot 521895 but not the svn one. Do I need the svn version ? Do
> > I need a newer version ?
>
> Snapshot should be fine. I don't know if you need svn to build the
> docs, though.

If you don't get it to work with the snapshot, download latest svn (see below)

Try to
$ make -f Makefile.cvs
$ ./configure

first, this should create appropriate makefiles with the apidox target. If 
that doesn't work, check out svn.


....... I just checked with the release candidate of koffice 1.5, it did have 
the "apidox" target after running ./configure. Please make sure you have 
doxygen installed and in your $PATH. But if you don't get anywere soon, just 
check out the svn version - that's more suitable anyway since you can keep 
track of changes with svn up and create patches with svn diff.

>
> > - How should I enable the generation of APIDOX from the Koffice
> > project ? Should I follow the APIDOX tutorial :
>
> I haven't taken the time to learn the syntax :( so I'm not much help.

If you have a svn checkout, you should call
$ make -f Makefile.cvs
$ ./configure

Then you can just generate the apidox by calling:
$ cd kplato
$ make apidox

that should work, also for kplato only (and not entire koffice)

>
> You'll also find a lot of wrong formatting along with incomplete
> comments etc.
>
> > http://developer.kde.org/documentation/library/howto.php#build
> >
> > This seems to be already enabled in Koffice. Should I regenerate
> > the Makefiles then ?
> >
> > At the moment, I get the following message :
> >
> > pagalmes at linux:~/Desktop/koffice-521895> make apidox
> > make[1]: Entering directory `/home/pagalmes/Desktop/koffice-521895'
> > make[1]: Nothing to do for « apidox-am-toplevel-no ».
> > make[1]: Leaving directory `/home/pagalmes/Desktop/koffice-521895'
> >
> > Any idea how to make it work ?

yes, I suppose that the tarball does not have the apidox target (for whatever 
reason). You might also check whether you have doxygen installed.

At least I can confirm that the apidox target is available in the svn version 
without having to manually change the Makefile(s).

To checkout the latest (trunk) KOffice sources:
http://www.koffice.org/download/unstable.php

Please note that you should use trunk, the svn URL is:
svn co svn://anonsvn.kde.org/home/kde/trunk/koffice

> >
> > - How can I generate only doc for the Kplato module and not for the
> > others applications ?

you can just "cd kplato && make apidox", that should do. That is, if you have 
the apidox target at all (should be available at least in the svn sources) 

> >
> > - Is there an IRC channel where you go to ?
>
> Not I, possibly Raphael?

I suppose #kde-docs would be the most suitable, but I don't know any specific 
for API docs. ... but, you might want to talk to [ade] on #kde-freebsd or 
wherever he happens to be in, he is the person to talk to for anything API 
docs related within KDE (Adriaan de Groot).

http://www.doxygen.org also has a nice manual.

Please note: http://www.englishbreakfastnetwork.org/sanitizer/index.php
(just click your way through to koffice/kplato)

>
> > - In which way should I provide the comments ? Do you want a diff
> > file ? the original file ? Any other format ?
>
> diffs are fine, diff -u3 to get some context.
>
> > As I will go to a place with not internet next week, I would like
> > to have an entire system setup for writing and testing this
> > documentation system before sunday. That way I will start working
> > on apidox during the evenings.
>
> Fine :) and thanks.
>
> > Thanks

... I hope we got all your questions answered (maybe not in a very structured 
way...), if you have any questions or problems left, please let us know.

Note that if you use svn, you can create patches simply with "svn diff", these 
should be fine for sending to the mailing list. Thanks a lot.

Regards,
Raphael