[dev] Source-level documentation

[Jon Parise]

I was just comparing the current forms of source-level documentation
that we generate here:

    http://dev.horde.org/api/horde/

Out of the lot, I think the phpdoc version is the least useful, the
DHTML version is the prettiest, and the Doxygen version has the most
potential.

I'm slightly biased because I use Doxygen for so many other projects
right now, but I think it may be preferrable to start using
Doxygen-style tags instead of phpdoc.

My reasoning:

 -  Doxygen supports a richer set of commands than phpdoc, and it
    allows more structured documentation formatting.  See:

        http://www.stack.nl/~dimitri/doxygen/manual.html

 -  Doxygen supports more output formats; in addition to HTML, it can
    generate: XML, LaTeX, RTF, PDF, Windows Help format

 -  Doxygen runs faster and is easier to automate than phpdoc.

 -  Doxygen development is steady while phpdoc development is not.

 -  Doxygen mostly supports a superset of the phpdoc commands,
    although some of the phpdoc are now used (i.e. @access).

 -  I like Doxygen better than phpdoc. =)

The Doxygen HTML output on the current dev.horde.org is not the
prettiest thing in the world, but it's quite simple to alter its
appearance by specifying a new style sheet.

Also, switching to a more "complete" documentation system will
hopefully promote better documentation practices, which will in turn
help us produce better API and development documentation for our
users.

Anyway, that's my little mini-sermon on why I think Doxygen is neat
and of use to the project.  I've been hearing talk about phpdoc being
rewritten / updated / improved for almost two years now, and I have
yet to see anything exciting come of it.

-- 
Jon Parise (jon@horde.org) :: The Horde Project (http://horde.org/)