PHPDoc is an adoption of Javadoc to the PHP world. It's basically a large PHP script that scans source code files for certrain markup and tries to build an API documentation. Even if your code does not contain the suggested "doc comments" PHPDoc will provide a raw documentation. See the online demo page to get an idea on what all this is about.

The current version 1.0beta has one major limitation. PHPDoc does not have a real parser, it simply greps the informations out of the given files. This is buggy by design.

A parser is a programm that scans a text word by word (or even sign by sign) and always knows what kind of element was last, what kind of element the current one is (state) and what's allowed next (syntax check). Based on this informations the parser builds a parsing tree that for example shows how elements are nested.

PHPDoc 1.0beta does not have such a parser it uses regular expressions to "parse" the code, it does a simple grep. This causes problems as you don't know anything on the current position of a match. The below example will not confuse a real parser but a grep (as implemented in 1.0beta) will find three functions.

How to trick PHPDoc 1.0beta

/** * Demonstration on how to trick PHPDoc */ function foo() { $bar = "function bar() {"; } // end func foo /** * Still more confusing for PHPDoc. * Mixed procedural and OO code in ome file */ class barfoo { /** * Is this a constructor inside a class or outside. * A grep doesn't know about it. */ function barfoo() { } // end constructor } // end class barfoo

As I know about this how can I say PHPDoc is a script you should have a closer look at? If you follow certain rules the results will be quite all right as you can see on the demo page.

• one class per file
• eigther procedural or OO code in one file

Now that we have a backward compatible parser module based on a grep, the next logical step must be to write a new php function that gives us access to the PHP/Zend parser so that "power users", which are the main focus for PHPDoc, get a reliable tool. Well see what's gonna happen. Help is appreceated.

<< Documentation Index | Installation >>