[dev] Source-level documentation

[Jon Wood]

What sort of features would you like to see in PHPDoc? I'm out of things to
do at the moment, and would be willing to add new features to it if I know
what's needed. I also watch the PEAR Dev list, and there has been talk of
releasing some of the component parts of Horde as seperate PEAR modules, and
since PEAR uses PHPDoc for it's documentation, at least those components
would have to be backwards compatible.

I just think that instead of moving software, since I have some time to
burn, it might be a better solution in the long term to add the features
people want to PHPDoc, since it was designed from the begining to document
PHP code, instead of (admittadly very similar) C code.

Just my 2 cents...

Jon Wood
----- Original Message -----
From: "Jon Parise" <jon@horde.org>
To: <dev@lists.horde.org>
Sent: Sunday, October 20, 2002 11:26 PM
Subject: [dev] Source-level documentation


> 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/)
>
> --
> Horde developers mailing list
> Frequently Asked Questions: http://horde.org/faq/
> To unsubscribe, mail: dev-unsubscribe@lists.horde.org