API documentation tools, coding standart

Hi,

Before we have too much changes in the 2.1 branch, I would like to
choose a tool to maintain the API documentation/reference. My first
release drove me nuts already. To maintain the index.html file any
longer is a no-no :).

I have no real preference for one tool or another but instead some requirements:
- do not force me to write 100 lines of comments but focus on the contents
- ability to generate html, text, latex, pdf, ps formats
- if possible widely spread so we can rely on distributions package

So far two tools match these requirements:

- Doxygen
- Robodoc

I do not like the output of doxygen (html for example) but I think it
can be customized. Robodoc comments are slightly larger but that's
acceptable.

Do you have any good or bad experiences with one of these tools? Or do
you have another suggestion?

Please keep in mind that I'm only talking about the API documentation.
Tutorials and other real documentations can be done in the wiki or
using any format (we can always convert them to put them online or as
downloads).

While being at it, I will also cleanup the code once and apply some
kind of coding standard and try to stick to them. I will use the PHP
Coding Standard, you can see a description here:

http://cvs.php.net/viewvc.cgi/php-src/CODING_STANDARDS?revision=1.32.4.3&view=markup

I hope it will minimize the pain for the packages if I make all these
changes in one or two commits.

Comments and feedbacks welcome!

Thanks for your attention,

--Pierre