PhpDocumentor, is an influential tool that permits to effortlessly document code through especially formatted comments. The documentation will be available not only in the source code, but also in professional documentation extracted using either the web or command-line interface. The result can be in various formats such as HTML, PDF, and CHM. Additionally, many IDEs that provide code-completion can parse PhpDoc comments and provide useful features such as type-hinting. PhpDoc make it easy for others to understand code – weeks, months, and even years after being written.

PhpDocumentor 2 is a tool that makes it possible to generate documentation directly from your PHP source code. With this you can provide your consumers with more information regarding the functionality embedded within your source and not just what is usable to them from your user interface.Documentation generated by phpDocumentor 2 does not aim to be a replacement for conventional documentation but is rather supplemental, or reference, documentation.This proves to be useful in the following example situations:

Sets of libraries or applications providing an API, such as phpDocumentor 2 itself
Frameworks, such as Zend Framework or Symfony
Pluggable architectures, such as WordPress or PyroCMS
Long-running, complex projects, to help you find the right function or method for the job
Templates
Templates
phpDocumentor 2 contains an incredibly flexible template system which enables you to alter your output in any way imaginable. This can range from simply applying your own branding for the HTML output by merely altering a couple of CSS files to determining which types of output are generated and where they are made available.

Code Analysis
Code Analysis
phpDocumentor 2 is capable of extracting interesting information and presenting it in the form of graphs and reports. The following are currently supported:

An inheritance diagram showing all subclassing and implementing of interfaces.
Reporting errors in your source code’s inline documentation.
Reporting which elements are marked as deprecated.
Reporting where TODOs are placed in your code and what is to be done.
This list will only grow in the future to help you determine where to invest your resources in order to make your code more stable and maintainable.

DocBlocks
A DocBlock is a multi-line C-style comment used to document a block of code. It begins with /** and has an asterisk at the start of each line. DocBlocks consist of three sections: short description, long description, and tags. All three sections are optional.The short description is a succinct description terminated by either a new-line or a period. PhpDoc’s parsing routines are smart; it will only end the short description if the period is at the end of a sentence.

The long description is where the bulk of the documentation goes; it can be multi-line and as long you wish.Both the long and short descriptions may contain certain HTML elements for formatting. HTML tags that aren’t supported will be displayed as plain text. PhpDoc can generate the documentation in multiple formats, though, so the HTML tags aren’t necessarily rendered as they would in an HTML file; the actual formatting depends on the generated file format. If you need to display an HTML tag as text, use double brackets.

The tags section of a DocBlock contains any number of special tags denoted by the @ symbol. The tags are used to specify additional information, such as the expected parameters and their type. Most tags must be on their own line, with the exception of certain tags which may be inline. Inline tags are surrounded with curly braces and may be in both the long and short description.

PhpDoc will automatically recognize textual lists in the long and short descriptions and it will parse them. However, it won’t parse nested lists correctly. If you want to use nested lists, use the HTML tags

Packages
PhpDoc packages are used to group related code elements in the generated documentation. You can specify packages for files and classes and the documented code they contain will inherit the package from them. To specify a package, set the @package tag in a file-level or class-level DocBlock.may contain letters, numbers, dashes, underscores, and square brackets (“[” and “]”).If you have multiple levels of packages and sub-packages, you can define a sub-package with the @subpackage tag.If a file or class doesn’t specify a package it will be set to the default package, “default”. You can specify a different package to be used by default when generating the documentation via the -dn command-line option.

What we can  Document?

Here is a list of code elements that may be documented:

Files
Classes
Functions and methods
Class properties
Global variables
include()/require()
define()
All of these elements can use certain common tags, but each has tags that are specific to that element. I’ll go over a few of the elements and the tags normally used to document them.

Files
File-level DocBlocks are used to document the contents of a file. It is highly recommended to include a file-level DocBlock in every file you document, and in fact PhpDoc will display a warning if one is not found when generating documentation.Most elements are documented by placing a DocBlock before the element, but files are an exception . File-level DocBlocks are placed on the first line of the file.

A file-level DocBlock usually contains the tags @package, @subpackage, @license, and @author. The @package and @subpackage tags were discussed earlier. The @license tag is used to specify a URL to an external license that covers your code. The tag must contain the URL to the license and optionally a title. The @author tag is used to specify the author of the file. It must contain the author’s name and optionally an email address in angle brackets.Unlike most elements, a file-level DocBlock must contain a @package tag in order to be parsed properly.

Classes
A class-level DocBlock is placed before a class definition and should describe the meaning of the class. Like file-level DocBlocks, class-level DocBlocks usually contain the tags @package, @subpackage, and @author.

Functions and methods
Functions and methods are documented identically in PhpDoc. (For those who may not be familiar with the terminology, a method is just a function within a class.) Functions and methods usually contain the @param and @return tags in their DocBlocks. The @param tag is used to document the expected type of a parameter. It contains three sections: the parameter, the data type, and an optional description. The @return tag is used to document the return type. It contains two sections: the data type and an optional description. In both tags, the data type can be either a valid PHP data type, a class name, or “mixed”. It can also contain multiple options separated by a pipe.

Generating Documentation
Once you’ve documented your PHP code, you’ll want to generate user-friendly documentation from it. To do so, run the PhpDoc command-line tool.The -d option specifies a comma-separated list of directories containing files to document, and -t the path to generated docs. -ti is used to specify the project title, and -dn to set the default package name. Finally, -o specifies the documentation format. PhpDoc has a wide selection of formats to choose from.Once you run the command, the documentation path you specified should contain the generated docs.

<?php

phpDocumentor is the current standard auto-documentation tool for the php language.

Config

Files

Output

Options

Similar to Javadoc, and written in php, phpDocumentor can be used from the command line or a web interface to create professional documentation from php source code. phpDocumentor has support for linking between documentation, incorporating user level documents like tutorials and creation of highlighted source code with cross referencing to php general documentation.

Major Features Of phpDocumentor

• output in HTML, PDF (directly), CHM (with windows help compiler), XML DocBook
• very fast
• web and command-line interface
• fully customizable output with Smarty-based templates
• recognizes JavaDoc-style documentation with special tags customized for PHP 4
• automatic linking, class inheritance diagrams and intelligent override
• customizable source code highlighting, with phpxref-style cross-referencing
• parses standard README/CHANGELOG/INSTALL/FAQ files and includes them directly in documentation
• generates a todo list from @todo tags in source
• generates multiple documentation sets based on @access private, @internal and {@internal} tags
• example php files can be placed directly in documentation with highlighting and phpxref linking using the @example tag
• linking between external manual and API documentation is possible at the sub-section level in all output formats
• easily extended for specific documentation needs with Converter
• full documentation of every feature, manual can be generated directly from the source code with “phpdoc -c makedocs” in any format desired
• user .ini files can be used to control output, multiple outputs can be generated at onceIntroduction

How to use  phpDocumentor