James Titcumb

There is a really easy way to document PHP (from a technical perspective anyway), and it’s known as phpDocumentor (or phpdoc for short).

Most good PHP IDEs (Eclipse PDT, PhpED, and probably Zend Studio, but I have not tried that) will support the language, which is actually pretty easy to remember and use anyway. phpdoc is just comments that are formatted in a special way. Phpdoc notation is like a normal comment, but is preceeded by /** instead of the regular /*. There are several special keywords that one can use as well to assist in documentation.

The other great thing about phpdoc is that the IDE (Eclipse PDT and PhpED do this) picks up on the variable types specified before a function, which makes code tooltips much more efficient.

Have a look at some sample phpdoc’ed code (not checked for syntax!):

<?
	/**
	 * File description goes here
	 */
 
	/**
	 * Class description goes here
	 *
	 * @name ClassName
	 * @version 1
	 * @package PackageName
	 */
	class ClassName
	{
		/**
		 * This variable holds some information
		 */
		private $SomeMember = 5;
 
		/**
		 * This function does something
		 *
		 * @param String $some_arg1 A string to be echoed out, prepended by Hello:
		 * @param OtherClass $some_arg2 The object containing a number that will form part of the division function.
		 * @return Number The value after the division.
		 */
		public function DoSoemthing($some_arg1, $some_arg2)
		{
			echo "Hello: {$some_arg1}";
			return $some_arg2->SomeNumber / $this->SomeMember;
		}
	}
?>

As you can see, just formatting the comments a bit better makes things clearer. The step after is to generate the documentation, which is an automatic process and more can be found on the phpDocumentor website.