Talk In Code

If you followed the tutorial on installing PHPDoc then you are probably wondering how to get started actually writing the documentation. PHPDoc will parse all the files given to it and look for comment blocks, it will then use these blocks to create the documentation for your application. A valid PHPDoc comment block must start with a '/**', have a '*' on every line and finish with '*/'. The comment must appear before the section that is being commented upon and any lines within the comment without a '*' will be ignored by the parser.

To create some sample documentation we will use the following useless class.

<?php
include('another_file.php');
 
class MyClass
{
 
  public $publicVariable = 123;
  private $privateVaraible;
 
  public function aFunciton($parameter)
  {
    // some code here...
  }
 
}

The first thing we need to do is create a file comment, this comment is intended to tell people what this file contains. In this example the file contains a single class definition and an include statement.

/**
 * MyClass File (short description about the file)
 *
 * This file contains the definition of the file MyClass (a longer description about the file).
 * @author A.N. Other
 * @version 1.0
 * @package MyPackage
 */

Notice the use of the @ symbol. This is called a tag and allows PHPDoc to assign values to internal variables. So when we use @version, we are setting the version variable for our file.

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented. So the next step is to document what the include statement includes. PHPDoc will attempt to find any files referenced through include or require statements and generate documentation for those files. If present, a link will be created from this file to that file in the documentation.

/**
 * Include the another_file.php file.
 */
include('another_file.php');

Next is our class definition, which consists of two forms of description(short and long) as well as some tags relating to things like what package the class is in.

/**
 * This is a short description about the class.
 *
 * This is a longer description which should detail exactly what the class does.
 * @package test
 * @author A.N. Other
 * @version 1.0
 * @copyright A copyright notice, if any.
 */
class MyClass
{
}

The two variables within the class must also be documented.

/**
 * A description of the variable.
 * @var integer
 */
public $publicVariable = 123;
 
/**
 * This variable will only appear in our documentation is we set the --parseprivate attribute on the command line or it has been set up in the INI file.
 * @access private
 * @var string
*/
private $privateVaraible;

Finally, we document the function. The functions are documented using the two tags of @param and @return. The @param can be defined multiple times and is a descriptive list of the parameters that the function takes. The @return value can only be defined once and describes what the function returns. If more than one datatype is returned from the function then they can be separated by a pipe (|).

/**
 * This class either returns an integer or a string.
 * @param A description about the parameter $parameter
 * @return string|int This function returns a string or an integer.
 */
public function aFunciton($parameter)
{
  // some code here...
}

To add more than one parameter just add another line in that starts with @param.

You can run PHPDoc on this file by using the following command (assuming that your project is kept in a folder called "MyProject" and that you want the documentation to go in "docs" within that directory.

C:\MyProject>phpdoc -t "C:\MyProject\docs" -o HTML:frames:default -d "C:\MyProject"

In my last post I talked about the PHP CodeSniffer, so today I thought I would solve a common problem that doesn’t seem to have any documentation. Whilst correcting a class file I had there was this one warning that just wouldn’t go away.

FILE: myclass.php
--------------------------------------------------------------------------------
FOUND 0 ERROR(S) AND 1 WARNING(S) AFFECTING 1 LINE(S)
--------------------------------------------------------------------------------
11 | WARNING | PHP version not specified
--------------------------------------------------------------------------------

There is no documentation (that I could find) on the CodeSniffer site about how to solve this, so I dove into the source files for the CodeSniffer extension and found this line.

* PHP Version 5

Add this to the file docs at the top of your file. You can change the version to be more specific if you wish, so if your class required at least PHP version 5.0.1 then use this as the version. I hope this little snippet helps someone.