[Phpwebsite-developers] PhpDocumentor and Code Comments

[Wendall C. <wen...@to...>]

Hello all,

Ok, I have a proposal to make for the project. I would like to see this
fully implemented in 1.0 and think it could easily fit with 0.9.x with a
minor amount of tweaking.

PEAR has a package some of you may have noticed called PhpDocumentor. I
have noticed this package many times, since it is used quite frequently
by other php projects.

Description:
The phpDocumentor tool is a standalone auto-documentor similar to
JavaDoc
written in PHP. It differs from PHPDoc in that it is MUCH faster, parses
a much
wider range of php files, and comes with many customizations including
11 HTML
templates, windows help file CHM output, PDF output, and XML DocBook
peardoc2
output for use with documenting PEAR. In addition, it can do PHPXref
source
code highlighting and linking.

You can find the package information here:
http://pear.php.net/package/PhpDocumentor

The output is pretty awesome if you see it in action. This is an
excellent way of documenting any classes. I think phpWebSite is optimal
for this type of documentor.

The manual is here:
http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html

Here is an example:
phpDocumentor tags are very similar to tags for the JavaDoc tool for
Sun's Java Programming Language. Tags are only parsed if they are the
first thing on a new line of a DocBlock. You may use the @ character
freely throughout documents as long as it does not begin a new line. An
example:

1     /**
2      * tags demonstration
3      * @author this tag is parsed, but this @version tag is ignored
4      * @version 1.0 this version tag is parsed
5      */

There are quite a few @ flags for use within comments to assist with
documentation. I feel that the current documents would work well with
PhpDocumentor. This example is nothing new to most of you, since
comments like these are scattered throughout phpws code. However, a
standard has never really been established. 

Here is an example of it in use:
http://manual.phpdoc.org/HTMLSmartyConverter/PHP/elementindex_HTML_TreeMenu.html

All the test pages there are generated using PhpDocumentor.

In short, I am proposing that we adopt the PhpDocumentor style and use
it throughout phpWebSite as the official comment style, so we can use
auto-documentation tools.

This has several benefits, since we can generate documentation straight
from code. I always find the energy and time to add a comment for a
function when I add it, but rarely do I have the energy to writeup
documentation after the fact. This will solve alot of this issue by
making all the very nice samples and comments available in a readable
format for developers to use. It would also be an excellent tool for
attracting new module developers. This may be a quick and dirty way for
us to make up for the poor documentation sins of the past. A few tweaks
here and there to some comments and run PhpDocumentor against phpWebSite
and we have something to start with.

I worked a little bit last night on creating UML diagrams of existing
code with AutoDia http://droogs.org/autodia/using.html It works quite
well and can be paired with the output of PhpDocumentor.

I will give some time to generating some reports on what needs to be
added/modified on the existing code base. I'm sure most things will work
in their current state, but some of the @ may need modified or added for
more accurate output. We can create a cheat sheet for the @ comment
flags available for use with PhpDocumentor. However, the tutorial is
pretty straight forward about what can be used and how.

Wendall