API Documentation

[Benedikt Meurer]

Jasper Huijsmans wrote:
> On Thu, Jan 29, 2004 at 10:56:26PM +0100, Benedikt Meurer wrote:
> 
> Right, I just modified the gtk-doc style comments in
> xfce-desktop-entry.c and turned them into doxygen style comments in the
> header file. Seems to work nicely. 
> 
> I saw you didn't add the documentation itself yet, was there a reason
> for that? 

Yep. With one project at work, we used to keep the doxygen generated 
documentation in CVS and its a mess. Though it has only around 100 classes, 
changing one class and running doxygen, causes nearly every html file to be 
regenerated and this fucks up the CVS logs.

I will add a Makefile to the docs/ directory soon and add a "doc" target to 
the main Makefile. This way we can generate documentation on-demand and we can 
even make "dist" depend on "doc" and therefore ship tarballs with up-to-date 
documentation. I think this is the best way to handle the stuff.

> We should install it somewhere as well, but I haven't looked at how to
> do this yet. Also it would be nice to have some text on the main page. 
> 
> I just played around a bit and added a file called MAINPAGE to the docs 
> directory with a very short introduction and added MAINPAGE to the INPUT 
> variable in the Doxyfile. That seems to work well.
> 
> docs/MAINPAGE
> ==================================
> /**
> 
> @mainpage Utility library for XFce
> 
> This library contains non-graphical utility functions for use by all
> components of the XFce Desktop Environment:
> - Debug functions.
> - Internationalization functions.
> - Location of user data.
> - Manipulating UTF-8 text.
> - Handling of desktop entry files.
> 
> */
> ===================================

 > What do you think?

I'd say go on and commit it.

> I'd also like to have an automatic index for API docs as well as regular
> documentation, but that's a bit more involved ...

I would like to see the API documentation available on the homepage. One 
stable API documentation containing the docs of the stable tree (ones we have 
docs in there or after we released 4.2) and one with nightly generated CVS 
docs (generating and uploading docs from a script is easy). Francois or 
Olivier, can we manage to get this working in the near future?

regards,
Benedikt

-- 
NetBSD Operating system:                       http://www.NetBSD.org/
pkgsrc "Work in progress":                  http://pkgsrc-wip.sf.net/
XFce desktop environment:                        http://www.xfce.org/
German Unix-AG Association:                   http://www.unix-ag.org/
os-network:                                 http://www.os-network.de/

OpenPGP Key: http://www.home.unix-ag.org/bmeurer/#gpg