phpDocumentor

Jussi Pohjolainen

TAMK University of Applied Sciences » ICT

Why Document?

• Lack of documentation costs
• Programmers usually forget the importance of documenting their code
• Easiest way to produce documentation is to add the documentation to the source code
• phpDocumentator is a tool that can extract source code comments and produce documentation.

Installation of phpDocumentator

• Easiest way: use PEAR command line interface (FAQ)
• phpDocumentor package can be found from http://www.phpdoc.org
• Unarchive the package: tar -xvzf PhpDocumentor-1.x.tgz
• After this, move to the package root: cd PhpDocumentor-1.x
• And finally use PEAR to install phpDocumentor: pear install package.xml
• Install guide can be found from PhpDocumentor-1.x/INSTALL

Generating Documentation

• You can generate documentation using web-based UI or command line tool
• Command line tool is called phpdoc
• Usage:

  phpdoc -d myapp/source
         -t myapp/docs
         -ti 'Title'
  

• All the options: phpdoc -h
• Even an a undocumented project, the phpdoc produces a documentation. See example: greetings.php and documentation

DocBlock comments

• DocBlock comments are source code comments that phpdoc recognizes
• DocBlock comments uses standard multiline comment style with an addition of one asterisk-char to each line:

  /**
   * This is my DocBlock comment.
   */
  

• DocBlock contains three basic segments: (1) Short description, (2) Long description and (3) Tags

Example of a DocBlock comment

/**
 * Return the date of Easter.
 * 
 * Using the formula from "Formulas that are way too complicated for anyone to
 * ever understand except for me" by Irwin Nerdy, this function calculates the
 * date of Easter given a date in the Ancient Mayan Calendar, if you can also
 * guess the birthday of the author.
 *
 * @sometag value
 */

Documentable PHP Elements

• Following elements can be documented:
  • Files and Classes
  • Procedural Elements: include / require / include_once / require_once / define / functions / global variables
  • Class Elements: variables / methods
• Every element can have standard phpDoc tags

About Packages

• Packages are used to group elements. Package can contain classes and procedural pages.
• There are two ways to use package: page-level and class-level
• If package is defined in page-level, all the functions, includes and defines belong to that package.
• If package is defined in class-level, then the class is part of that package.
• Each file and class should be in a package! (avoid name conflictions)
• Class and file should have same package

Documenting file

• It's possible to document information about the entire file: Page-Level DocBlock
• Page-level DocBlock is the first DocBlock in a file. Page-Level DocBlock must contain @package tag.
• Page-Level DocBlock can have standard phpDocumentor tags

/**
 * Page-Level DocBlock, short description here.
 *
 * Longer file description and other paragraphs here.
 *
 * @package   mypackage
 * @author    Jussi Pohjolainen
 * @version   2008-03-24
 */

Commenting classes

/**
 * One line class description here.
 *
 * Longer class description and other paragraphs here.
 *
 * @package  my-package-name
 * @author   my-name
 * @version  2007-04-03
 */
class FooBar
{

}

Errors and warnings

• Errors and warnings are generated to errors.html
• Most common warning is about Page-level DocBlocks. Each file and class should have their own DocBlock.

Example of a file and class

/**
 * This is a file-level DocBlock.
 *
 * @package SomePackage
 */
 
/**
 * This is a not a file-level DocBlock, because it precedes a class declaration.
 *
 * @package SomePackage
 */
class Foo {}

• See example Point.php and the documentation

Documenting Class Properties

• phpDocumentor allows you to document property type using @var tag.
• Example:

  
  class Cat
  {
      /**
       * Cat's name.
       *
       * @var     string
       * @access  public
       */
      public $name;
  }
  

• Only the public properties are shown in documentation. Private properties can be shown by using -pp on option

Documenting Class Methods

• Class method can have the standard phpdoc tags and the following:
  • @global - If global variable is used in method
  • @param- Method parameter
  • @return - Return type
  • @static - Document if a class or method is static
  • @staticvar - If static variable is used in method

Simple Class Method - example

/**
 *  Short description.
 *
 *  Long description.
 *
 *  @access public
 *  @param  string  $foo  description here
 *  @param  string  $bar  description here
 *  @return boolean       description here
 */
public function MyMethod ($foo, $bar)
{
   ...
   return true;
}

Style Guide in A-OT03 » General ( 1/3 )

• Write everything in English
• Use ISO 8601 standard in dates
• Every file starts with a "GNU GPL v2 or later" -license
• Every php source code ends with "// End of file" string

Style Guide in A-OT03 » phpDoc Tags ( 2/3 )

• Write method tags in this order: 1) @access, 2) @param and 3) @return.
• Example

  
  /**
   *  Short Description.                                    
   *
   *  Longer description. If there were any, it would be    
   *  here.
   *
   *  @access public                                        
   *  @param  integer  $x  description about the parameter
   *  @param  integer  $y  description about the parameter
   *  @return bool         description about the return type
   */
  

Style Guide in A-OT03 » @var ( 3/3 )

• Use @var to document the type of a variable
• Example

  
  /**
   * An instance of this class or null if no open database connection.
   *
   * @access  private
   * @var     object
   * @static
   */
  private static $objInstance = null;
  

Links

• Detailed coding styles: Coding Style: A-OT03
• phpDocumentor
• Tutorial