PHPDoc is an attempt to adopt Javadoc to the PHP world. PHPDoc does not have the power Javadoc offers, but it's quite useful to document your PHP source and always remember "this is alpha stuff".

PHPDoc is free (GPL). Nevertheless please do not distribute this version and even this URL. I don't want a public beta test, I'm not a friend of public alpha tests, I just need some feedback from a few guys. PHPDoc will become public, as soon as all major bugs are wiped out.

Installation

Installation is trivial. Download the Zipfile phpdoc0.1alpha.zip (32kb), extract it and place it somewhere on your webserver. Start index.php3 or index.php4.
If PHP complains on the include path, edit prepend.php3.

PHPDoc will extract the inline documentation from its source and write some HTML Files in the directory apidoc/. When it's finished and everything is fine it shows you a list of the generated files.

How can I test PHPDoc with my source?

I'm afraid to tell you, that I didn't spend much time in this yet. Currently you should modify the index.php[34] and use the given commands. PHPDoc is prepared to handle command line requests (core/PhpdocArgvHandler.php) but the code is completely untested. Functions such as setDirectory() which could (recursively) scan a directory and automatically document all files it finds will follow later.

Note that PHPDoc works only on classes.

How to write Inline Documentation

If you don't know Javadoc, please read the instructions given by Sun How to write Javadoc comments. I will give you only a brief overview on the features that I adopted to PHPDoc. Within the instructions I'll always give some notes on how it is realized in the source code and which part of PHPDoc does this job.

What does a documentation comment look like?

A documentation comment is multiple line comment starting with "/**" (two asterix) and ending with "*/". All subsequent lines start with "*". On the top of a documentation comment is the description. The first line is called "shortdesc" in the PHPDoc source and shown in summaries. All following lines before the comment ends of a tag appears, are called "$fulldescription"/"desc". This "desc" is only showed in the detail view of a variable, method or class.
Source: parser/PhpdocParserObject->getPhpdocParagraphs()

/** * Short description - first line, always shown in an overview table * * Full description, not shown in an overview table, just in the detail * view. Descriptions may contain <b>HTML</b> Tags. * The description ends where the */

Documentation comments are only recognized when they're followed by a certain keyword. PHPDoc uses a combination of regular expressions (preg.*) and strpos() to find the keywords.
Source: parser/PhpdocParserObject, all PhpdocXYParser->addUndocumentedXY()

	var
	function
	class

Tags?

PHPDoc tags look very much like Javadoc tags. They start with "@" followed by the tagname and the "tagvalue". Currently PHPDoc knowns ten tags:

	@abstract
	@access
	@author
	@param
	@return
	@see
	@since
	@throws
	@var
	@version

Source: parser/PhpdocParserObject->getTags(), parser/PhpdocParserObject->PHPDOC_TAGS

In constrast to Java you're currently not allowed to embed tags in the leading description paragraph of a documentation comment. There's no technical reason to do so; I simply preferred it that way, it makes reading the source a little easier.

As with documentation comments not every tag is allowed everywhere. It simply makes no sense to use @param in a class comment... He're what's recognized with a certian keyword:

	keyword class: @author @version @since @abstract
	keyword function: @param @return @throws @see @abstract @version @since
	keyword var: @var @access @see @since @version

Today there're no rules in which order you should write the tags in your comments. I suggest to take the order shown in the table above.

Limitations

One of the worst things on PHPDoc is, that it does not compare the PHP Source with your doc comment. This has some nasty side effects, e.g. the @param tag request you to specify the variable name which is only a few lines below in the PHP Source...

Tag Quick Ref

I'll just write a few lines on common tags. Please have it look at the Source to find out more on the syntax. Have an intensive look on parser/PhpdocParserObject. There're many regular expressions that get used when analysing tags.

@abstract

1. @abstract

Contact

You can contact me by email ulf@redsys.de or give me a call: +49 431 66 13 304. Mostly you'll meet me at home in the evening from 8-10pm.