Re: [Phpwebsite-developers] PhpDocumentor and Code Comments

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

Some sample output for core/ can be found here:
http://phpwebsite-comm.sourceforge.net/coredoc/li_Core.html

On Tue, 2005-01-18 at 07:00 -0800, Wendall Cada wrote:
> 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
> 
> 
> 
> 
> 
> 
> 
> 
> -------------------------------------------------------
> The SF.Net email is sponsored by: Beat the post-holiday blues
> Get a FREE limited edition SourceForge.net t-shirt from ThinkGeek.
> It's fun and FREE -- well, almost....http://www.thinkgeek.com/sfshirt
> _______________________________________________
> Phpwebsite-developers mailing list
> Php...@li...
> https://lists.sourceforge.net/lists/listinfo/phpwebsite-developers