phpDocumentor

phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to generate a complete set of API Documentation.

Inspired by phpDocumentor 1 and JavaDoc it continues to innovate and is up to date with the latest technologies and PHP language features.

Installation

Using Phive

$ phive install --force-accept-unsigned phpDocumentor

For more information about phive have a look at their website. Now you have phpDocumentor installed, it can be executed like this:

php tools/phpDocumentor

Using the PHAR

1. Download the phar file from https://github.com/phpDocumentor/phpDocumentor/releases
2. You can execute the phar like this: php phpDocumentor.phar

Via Docker

1. $ docker pull phpdoc/phpdoc
2. $ docker run --rm -v $(pwd):/data phpdoc/phpdoc

Via Composer (not recommended)

1. phpDocumentor is available on Packagist.

2. It can be installed as a dependency of your project by running

    $ composer require --dev phpdocumentor/phpdocumentor dev-master
   

Afterwards you are able to run phpDocumentor directly from your vendor directory:

$ php vendor/bin/phpdoc

Using phpDocumentor

The easiest way to run phpDocumentor is by running the following command:

$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

This command will parse the source code provided using the -d argument and output it to the folder indicated by the -t argument.

phpDocumentor supports a whole range of options to configure the output of your documentation. You can execute the following command, or check our website, for a more detailed listing of available command-line options.

$ phpdoc run -h

Features

phpDocumentor supports the following:

• PHP 7.0 compatible, full support for Namespaces, Closures and more are provided.
• Shows any tag, some tags add additional functionality to phpDocumentor (such as @link).
• Processing speed, Zend Framework experiences a significant reduction in processing time compared to phpDocumentor 1.
• Low memory usage, peak memory usage for small projects is less than 20MB, medium projects 40MB and large frameworks 100MB.
• Incremental parsing, if you kept the Structure file from a previous run, you get an additional performance boost of up to 80% on top of the mentioned processing speed increase above.
• Easy template building, if you want to make a branding you only have to call 1 task and edit 3 files.
• Command-line compatibility with phpDocumentor 1, phpDocumentor 2 is an application in its own right but the basic phpDocumentor 1 arguments, such as --directory, --file and --target, have been adopted.
• Two-step process, phpDocumentor first generates a cache with your application structure before creating the output. If you'd like you can use that to power your own tools or formatters!

Writing Comments

DocComments

A DocComment starts with a forward slash and two asterisks (/**), which is similar to how you start a multiline comment but with an additional asterisk, and ends with an asterisk and forward slash (*/). DocComments may be a single line in size but may also span multiple lines, in which case each line must start with an asterisk. It is customary, and recommended, to align the asterisks vertically when spanning multiple lines.

So, a single line DocComment looks like this:

/** This is a single line DocComment. */

And a multiline DocComment looks like this:

/**
 * This is a multi-line DocComment.
 */

Summary

The summary is a short but effective overview of an element; you can compare it to a slogan or headline. Summaries are plain and simple, they cannot contain formatting or inline tags (see the next chapter for more information on this) and can be used to skim through, for example, a list of methods.

The summary can be separated from the description in two ways:

1. With an empty whiteline:

   /**
    * This is a summary
    *
    * This is a description
    */
   

2. Or by adding a period followed by a new-line:

   /**
    * This is a summary.
    * This is a description
    */
   

Description

This is where the fun starts! A description can be a long text with an elaborate explanation what the associated element does. The description is optional, as there are many elements that are so straightforward that they do not need a length explanation.

Even worse: proper methods are often so simple that a description could be considered overkill!

The nice thing about this description is that you can format your text according to Markdown, more specifically Github-flavoured Markdown_. Using this format it is easy to make your text bold, add inline code examples or easily generate links to other sites.

Another nifty feature is that you can use a series of Inline Tags to refer to other parts of the documentation ({@see}), inherit the description of a parent ({@inheritDoc}) and more. Once you finish reading this guide you should definitely take a look at the Inline tag reference to see which Inline Tags there are and what they do.

The description can be as long as you would like and ends when a tag is encountered for the first time.

Tags

Tags are a type of specialized information (meta-data) about the associated element. At the time of writing of this guide PHPDoc counts twenty-eight (28) types of tags.

A tag always starts on a new line with an at-sign (@) followed by the name of the tag. Between the start of the line and the tag’s name (including at-sign) there may be one or more spaces or tabs.

The following is an example of a simple tag:

/**
 * @source
 */

In addition to their name each tag may have arguments that can provide additional context specific for that tag. The most common example of this is the @param tag, with which the argument of a method or function is documented:

/**
 * @param string $argument1 This is the description.
 */