phpDocumentor

Coding Style Index?

1.  "Who is my audience?"

1.1  2 types of documentaion:

1. end-user specific:
   • Instruction-style writing, that explains and describes general concepts more than how a particular variable is used
   • Interface information only, no low-level details
   • Examples of how to use, and tutorials
2. programmer specific:
   • Details on how program elements interact, which elements use others
   • Where in the source code an action or series of actions occurs
   • How to extend the code to add new functionality

In-code documents in your DocBlocks must be written for both end-users and programmers wherever possible. The ability to add succinct documentation in the source code is essential, it cannot replace the importance of verbose documentation that is not in the source code, such as a user manual, or tutorials such as the one you are reading now. If the text you see here were placed in the source code for phpDocumentor, it would serve little useful purpose, clutter up the code, and be difficult to locate. However, the ability to hyperlink between documentation in the source code and external documentation is essential.

External documentation for function foo must be able to reference the generated in-code documentation, and with phpDocumentor this is finally possible.

2.  Components of PHPDoc

Elements which can be documented:

• define() statements,
• functions,
• classes,
• class methods,
• class vars,
• include() statements,
• global variables.

2.1  DocBlock

DocBlocks precede the element they are documenting. Place the DocBlock immediately before the function declaration. It begins with "/**" and has an "*" at the beginning of every line. Any line within a DocBlock that doesn't begin with a * will be ignored.

3 basic segments in this order:

• Short Description
  • Short Description starts on the first line, and can be terminated with a blank line or a period
  • A period inside a word (like example.com or 0.1 %) is ignored
  • If the Short Description would become more than three lines long, only the first line is taken
• Long Description
  • Long Description continues for as many lines as desired and may contain html markup for display formatting.
• Tags

List of tags supported by PHPDocumentor:

• <b> -- emphasize/bold text
• <code> -- Use this to surround php code, some converters will highlight it
• <br> -- hard line break, may be ignored by some converters
• <i> -- italicize/mark as important
• <kbd> -- denote keyboard input/screen display
• <li> -- list item
• <ol> -- ordered list
• <p> -- If used to enclose all paragraphs, otherwise it will be considered text
• <pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
• <samp> -- denote sample or examples (non-php)
• <ul> -- unordered list
• <var> -- denote a variable name

If the symbol is at the beginning of a line, it is a standard tag, and if it is enclosed in {curly brackets}, it is an inline tag.

Similarly, if you need an actual "@" in your DocBlock's description parts, you should be careful to either ensure it is not the first character on a line, or else escape it ("\@") to avoid it being interpreted as a PhpDocumentor tag marker.

 If you need to use the closing comment "*/" in a DocBlock, use the special escape sequence "{@*}." Here's an example:

Lists:

phpDocumentor recognizes any simple list that begins with "-", "+", "#" and "o", and any ordered list with sequential numbers or numbers followed by "." as above. The list delimiter must be followed by a space (not a tab!) and whitespace must line up exactly, or phpDocumentor will not recognize the list items as being in the same list.

You must line up the list iterators in the same vertical column in order for those list items to be considered "on the same list". Also, you cannot create nested lists using the simple list iterators... doing so means it's no longer a "simple" list! Varying the spacing of the list iterators does not create nesting of the lists... it only starts up new simple lists. If you specifically need a nested list, you must use the list tags (<ol>, <ul>):

In some cases, the text description in a doc tag can contain a list, be it simple or complex. Notice that a title line is needed, with the list items themselves beginning on the next line:

Tagged lists are always a more robust and predictable option for you to use. Simple lists are convenient, but if you find yourself trying to bend a simple list into displaying a certain way in your generated docs, you may be better served by switching to a tagged list instead.

DocBlock Templates

DocBlock Templates reduce redundant typing. If a large number of class variables are private, one would use a DocBlock template to mark them as private. DocBlock templates simply augment any normal DocBlocks found in the template block.

A DocBlock Template stats with: /**#@+ and will be applied to all documentable elements until the ending template marker: /**#@-*/

Rules for merging:

• The long description of the docblock template is added to the front of the long description. The short description is ignored.
• All tags are merged from the docblock template.

Example:

It becomes:

A list of all possible tags in phpDocumentor follows:

Tag	Usage	Description
@abstract
@access	public, private or protected
@author	author name <author@email>
@copyright	name date
@deprecated		marks a method as deprecated.
@deprec		same as @deprecated
@example	/path/to/example
@exception		documents an exception thrown by a method — also see @throws
@global	type $globalvarname
@ignore
@internal		private information for advanced developers
@link	URL
@name
@magic
@package
@param	type [$varname] description
@return	type description	This tag should not be used for constructors or methods defined with a void return type.
@see		Documents an association to another method or class.
@since		Documents when a method was added to a class.
@static
@staticvar
@subpackage
@throws		Documents an exception thrown by a method.
@todo
@var	type	a data type for a class variable
@version		Provides the version number of a class or method.

In addition, using the @access tag, one can mark programmer-level elements with @access private, and they will be ignored by default. The @internal tag and inline {@internal}} inline tag construct can be used to mark documentation that is low-level or internal to a smaller audience of developers. When creating programmer documentation, turn on the parse private option (see -pp, --parseprivate), and the low-level detail will be generated.

In addition, tutorials/parsers allow two addition inline tags: {@id}, used to allow direct linking to sections in a tutorial, and {@toc}, used to generate a table of contents from {@id}s in the file. Think of {@id} like an <a name="idname"> HTML tag, it serves the same function.

In the example below, {@id} is used to name the refsect1 "mysection" and the refsect2 "mysection.mysubsection" - note that the sub-sections inherit the parent section's id.

3.  Documenting global variables

The @global tag is used to tell the parser how to find a global variable declaration. Without this tag, no documentation would be generated for $_myvar. The @global tag can take many forms - be sure to specify the type and global name, with no description, or the parser will generate a warning and fail to document the variable.

The @name tag is used to tell the parser how the global variable would be referenced by a global statement in a function. The @global tag here will associate the information with the declared global statements in the function body in the same order of their declaration.

4.  Page-level DocBlock warnings & Dividing projects into packages

phpDocumentor organizes procedural elements and classes into special groupings called packages. It requires an explicit @package tag, and will raise a warning any time this tag is missing from a top-level source element.

Rules:

1. If the first DocBlock in a file contains a @package tag, it documents the file unless it precedes a class declaration.
2. If the first DocBlock in a file precedes another DocBlock, it documents the file.

Page-level DocBlock may have any of the standard phpDocumentor Tags plus the following tags:

• @package
• @subpackage

The logic behind packaging in PHP:

The quest for structured programming led to the invention of functions, then classes, and finally packages. Traditionally, a re-usable software module was a collection of variables, constants and functions that could be used by another software package. PHP is an example of this model, as there are many extensions that consist of constants and functions like the tokenizer extension. One can think of the tokenizer extension as a package: it is a complete set of data, variables and functions that can be used in other programs. A more structured format of this model is of course objects, or classes. A class contains variables and functions. A single class packages together related functions and variables to be re-used.

phpDocumentor defines package in two ways:

• Functions, Constants and Global Variables are grouped into files (by the filesystem), which are in turn grouped into packages using the @package tag in a page-level DocBlock.
• Methods and Class Variables are grouped into classes (by PHP), which are in turn grouped into packages in a Class DocBlock.

These two definitions of package are exclusive. In other words, it is possible to have classes of a different package of the file that contains it.

It may be possible, but don't put classes into a different package from the file they reside in, that will be very confusing and unnecessary. This behavior is deprecated, in version 2.0, phpDocumentor will halt parsing upon this condition.

Perhaps the best way to organize packages is to put all procedural code into separate files from classes. PEAR recommends putting every class into a separate file. For small, utility classes, this may not be the best solution for all cases, but it is still best to separate packages into different files for consistency.

5.  Writing external documentation and linking to source code documentation

Although documentation parsed directly from source code is tremendously useful, it cannot stand on its own. In addition, truly useful in-code documentation must be succinct enough so that the code is not completely obscured by the documentation. External documentation is a must for a complete documentation solution. However, external documentation must be able to link to API source documentation to be useful. With a constantly changing API documentation, it is very easy for external documentation to become out of date. In addition, external documentation must be in a format that can be converted into other formats such as HTML, PDF and XML.

phpDocumentor provides a simple and elegant solution to all of these problems. External documentation in DocBook format can be easily converted to other formats. Using inline tags, phpDocumentor can generate a consistent manual in many different formats by combining the output from parsing the source and parsing external documentation.

DocBook-based file:

Linking to external documentation, and to sections of that documentation:

If phpDocumentor only could create HTML documents, this would be a simple task, but the presence of PDF and now XML converters as well as future possibilities complicates this question tremendously.

Give phpDocumentor the ability to parse external documentation in a common format and then convert it to the appropriate format for each converter.

The implementation of this solution in version 1.2.0 is very versatile. Making use of the standard DocBook XML format, external documentation can be designed and then reformatted for any output.

No longer is external documentation tied down to one "look." Here's a short list of the benefits of this approach:

Benefits of using DocBook as the format:

• DocBook is very similar to HTML at the basic level and very easy to learn.
• Each template has its own options.ini file which determines how the DocBook tags will be translated into the output language - no need to learn xslt.
• Adding in xslt support will be very easy to allow for future customization

Benefits of integrating tutorials/external documentation into phpDocumentor:

• Linking to external documentation from within API docs is possible
• Linking to API docs from external documentation is also possible
• Customizable table of contents, both of all tutorials and within a tutorial via inline {@toc}
• It is possible to create User-level documentation that has direct access to Programmer-level documentation

User-level documentation generally consists of tutorials and information on how to use a package, and avoids extreme detail. On the other hand, programmer-level documentation has all the details a programmer needs to extend and modify a package. phpDocumentor has been assisting the creation of programmer-level documentation since its inception. With the addition of tutorials, it can now ease the creation of user-level documentation.

6.  Running the command-line in unix

Running the command-line tool phpdoc is very easy in unix: .\phpdoc [commandline]

Command-line switches:

-cp, --converterparams
dynamic parameters for a converter, separate values with commas

-ct, --customtags
comma-separated list of non-standard @tags to pass to the converter as valid tags

-d, --directory
name of a directory(s) to parse directory1,directory2

-dc, --defaultcategoryname
name to use for the default category. If not specified, uses 'default'

-dh, --hidden
set equal to on (-dh on) to descend into hidden directories (directories starting with '.'), default is off

-dn, --defaultpackagename
name to use for the default package. If not specified, uses 'default'

-ed, --examplesdir
full path of the directory to look for example files from @example tags

-f, --filename
name of file(s) to parse ',' file1,file2. Can contain complete path and * ? wildcards

-i, --ignore
file(s) that will be ignored, multiple separated by ','. Wildcards * and ? are ok

-is, --ignoresymlinks
Explicitly ignore symlinks, both symlinked directories and symlinked files. Valid options are "on" and "offn" default value is "off"

-it, --ignore-tags
tags to ignore for this parse. @package, @subpackage, @access and @ignore may not be ignored.

-j, --javadocdesc
use JavaDoc-compliant description (short desc is part of description, and is everything up to first .)

-o, --output
output information, format:converter:template (HTML:frames:phpedit for example)

-p, --pear
Parse a PEAR-style repository (package is directory, _members are @access private) on/off default off

-po, --packageoutput
output documentation only for selected packages. Use a comma-delimited list

-pp, --parseprivate
parse elements marked private with @access. Valid options are "on" and "off" default value is "off"

-q, --quiet
do not display parsing/conversion messages. Useful for cron jobs. Valid options are "on" and "off" default value is "off"

-ric, --readmeinstallchangelog
Specify custom filenames to parse like README, INSTALL or CHANGELOG files

-s, --sourcecode
generate highlighted sourcecode for every parsed file (PHP 4.3.0+ only) on/off default off

-t, --target
path where to save the generated files

-ti, --title
title of generated documentation, default is 'Generated Documentation'

-tb, --templatebase
base location of all templates for this parse. Note that if -tb /path/to/here, then templates for HTML:frames:default must be in /path/to/here/Converters/HTML/frames/templates/default/templates and the /path/to/here/Converters/HTML/frames/templates/default/templates_c directory must exist, or Smarty will bail on attempting to compile the templates.

-ue, --undocumentedelements
Enable warnings for undocumented elements. Useful for identifying classes and methods that haven't yet been documented. Valid options are "on" and "offn" default value is "off"

-c, --config
Use this option to load a config file (see phpDocumentor's dynamic User-defined config files) "phpdoc -c default" will load the default.ini file

-cp, --converterparams
This option is only used to pass dynamic parameters to extended converters. The options passed should be separated by commas, and are placed in the global variable $_phpDocumentor_setting['converterparams'], an array. It is the responsibility of the Converter to access this variable, the code included with phpDocumentor does nothing with it.

-ct, --customtags
Use this option to specify tags that should be included in the list of valid tags for the current run of phpdoc "phpdoc -ct mytag,anothertag" will tell phpDocumentor to parse this DocBlock:

without raising any errors, and include the tags in the known tags list for the template to handle. Note that in version 1.2.0+, the unknown_tags array is passed to templates.

-dh, --hidden
Use this option to tell phpDocumentor to parse files and directories that begin with a period (.)

-dn, --defaultcategoryname
This will tell phpDocumentor to group any uncategorized elements into the primary categoryname. If not specified, the primary category is "default." The category should be specified using the @category tag.

-dn, --defaultpackagename
Use this option to tell phpDocumentor what the primary package's name is. This will also tell phpDocumentor to group any unpackaged elements into the primary packagename. If not specified, the primary package is "default"

-d, --directory
This or the -f option must be present, either on the command-line or in the config file. Unlike -f, -d does not accept wildcards. Use -d to specify full paths or relative paths to the current directory that phpDocumentor should recursively search for documentable files. phpDocumentor will search through all subdirectories of any directory in the command-line list for tutorials/ and any files that have valid .php extensions as defined in phpDocumentor.ini. For example: "phpdoc -d relative/path/to/dir1,/fullpath/to/here,.."

-ed, --examplesdir
The -ed option is used to specify the full path to a directory that example files are located in. This command-line setting affects the output of the @example tag. "phpdoc -ed /fullpath/to/examples"

-f, --filename
This or the -d option must be present, either on the command-line or in the config file. This option is used to specify individual files or expressions with wildcards * and ?. Use * to match any string, and ? to match any single character.

• phpdoc -f m*.p* will match myfile.php, mary_who.isthat.phtml, etc.
• phpdoc -f /path/m* will match /path/my/files/here.php, /path/mommy.php /path/mucho/grande/what.doc, etc.
• phpdoc -f file?.php will match file1.php, file2.php and will not match file10.php

-i, --ignore
Use the -i option to exclude files and directories from parsing. The -i option recognizes the * and ? wildcards, like -f does. In addition, it is possible to ignore a subdirectory of any directory using "dirname/".

• phpdoc -i tests/ will ignore /path/to/here/tests/* and /path/tests/*
• phpdoc -i *.inc will ignore all .inc files
• phpdoc -i *path/to/* will ignore /path/path/to/my/* as well as /path/to/*
• phpdoc -i *test* will ignore /path/tests/* and /path/here/my_test.php

Since v1.3.2, the value or pattern you provide will be case-sensitive (OS permitting, anyway), and will be applied relative to the top-level directory in the -d argument.

• phpdoc -i CVS/ will ignore /path/to/CVS/* but will not ignore /path/to/cvs
• phpdoc -d /home/myhome/cvs/myproject -i cvs/ will ignore /home/myhome/cvs/myproject/files/cvs/* but will not ignore /home/myhome/cvs/*

-is, --ignoresymlinks
Use the -is option to explicitly ignore any symlinks, whether they be links to directories or links to files. This only works on a Unix/Linux environment, since Windows doesn't have symlinks.

-it, --ignore-tags
Use the -it option to exclude specific tags from output. This is used for creating multiple sets of documentation for different audiences. For instance, to generate documentation for end-users, it may not be desired to output all @todo tags, so --ignore-tags @todo would be used. To ignore inline tags, surround them with brackets {} like --ignore-tags {@internal}. --ignore-tags will not ignore the core tags @global, @access, @package, @ignore, @name, @param, @return, @staticvar or @var. The --ignore-tags option requires a full tag name like --ignore-tags @todo. --ignore-tags todo will not work.

-j, --javadocdesc
Use this command-line option to enforce strict compliance with JavaDoc. JavaDoc DocBlocks are much less flexible than phpDocumentor's DocBlocks (see DocBlocks for information).

-o, --output
Use this required option to tell phpDocumentor which Converters and templates to use. In this release, there are several choices:

• HTML:frames:* - output is HTML with frames.
• HTML:frames:default - JavaDoc-like template, very plain, minimal formatting
• HTML:frames:earthli - BEAUTIFUL template written by Marco von Ballmoos
• HTML:frames:l0l33t - Stylish template
• HTML:frames:phpdoc.de - Similar to phpdoc.de's PHPDoc output
• HTML:frames:phphtmllib - Very nice user-contributed template
• all of the templates listed above are also available with javascripted expandable indexes, as HTML:frames:DOM/name where name is default, l0l33t, phpdoc.de, etcetera
• HTML:frames:phpedit - Based on output from PHPEdit Help Generator
• HTML:Smarty:* - output is HTML with no frames.
• HTML:Smarty:default - Bold template design using css to control layout
• HTML:Smarty:HandS - Layout is based on PHP, but more refined, with logo image
• HTML:Smarty:PHP - Layout is identical to the PHP website
• CHM:default:* - output is CHM, compiled help file format (Windows help).
• CHM:default:default - Windows help file, based on HTML:frames:l0l33t
• PDF:default:* - output is PDF, Adobe Acrobat format
• PDF:default:default - standard, plain PDF formatting
• XML:DocBook:* - output is XML, in DocBook format
• XML:DocBook/peardoc2:default - documentation ready for compiling into peardoc for online pear.php.net documentation, 2nd revision

In 1.2.0+, it is possible to generate output for several converters and/or templates at once. Simply specify a comma-delimited list of output:converter:template like: phpdoc -o HTML:frames:default,HTML:Smarty:PHP,HTML:frames:phpedit,PDF:default:default -t ./docs -d .

-pp, --parseprivate
By default, phpDocumentor does not create documentation for any elements marked @access private. This allows creation of end-user API docs that filter out low-level information that will not be useful to most developers using your code. To create complete documentation of all elements, use this command-line option to turn on parsing of elements marked private with @access private.

-po, --packageoutput
Use this option to remove all elements grouped by @package tags in a comma-delimited list from output. This option is useful for projects that are not organized into separate files for each package. Parsing speed is not affected by this option, use -i, --ignore whenever possible instead of --packageoutput. phpdoc -o HTML:frames:default -t ./docs -d . -po mypackage,thatotherpackage will only display documentation for elements marked with "@package mypackage" or "@package thatotherpackage"

-p, --pear
Use this option to parse a PEAR-style repository. phpDocumentor will do several "smart" things to make life easier:

• PEAR-style destructors are automatically parsed
• If no @package tag is present in a file or class DocBlock, it will guess the package based on subdirectory
• If a variable or method name begins with "_", it will be assumed to be @access private, unless an @access tag is present. Constructors are also assumed to be @access private in the current version.

Warnings will be raised for every case above, as @package should always be explicit, as should @access private. We do not like to assume that phpDocumentor knows better than you what to do with your code, and so will always require explicit usage or raise warnings if phpDocumentor does make any assumptions.

-q, --quiet
This option tells phpDocumentor to suppress output of parsing/conversion information to the console. Use this for cron jobs or other situations where human intervention will not be needed.

-ric, --readmeinstallchangelog
This comma-separated list of files specifies files that should be parsed and included in the documentation. phpDocumentor will automatically grab files listed here if and only if they are located in the top-level directory that is parsed. In other words, if you parse these files:

• /path/to/files/file1.php
• /path/to/files/file2.php
• /path/to/files/README
• /path/to/files/subdir/file2.php
• /path/to/files/subdir/README

The only README file that will be grabbed is /path/to/files/README, and not /path/to/files/subdir/REAMDE, because the directory that is closest to the root directory that contains a parsed file is /path/to/files. The default list of files is located in phpDocumentor.ini, which is found in the root installation directory of phpDocumentor.

-s, --sourcecode
This option tells phpDocumentor to generate highlighted cross-referenced source code for every file parsed. The highlighting code is somewhat unstable, so use this option at your own risk.

-t, --target
Use this to tell phpDocumentor where to put generated documentation. Legal values are paths that phpDocumentor will have write access and directory creation priveleges.

-tb, --templatebase
-tb accepts a single pathname as its parameter. The default value of -tb if unspecified is <phpDocumentor install directory>/phpDocumentor. This raises a very important point to understand. The -tb command-line is designed to tell phpDocumentor to look for all templates for all converters in subdirectories of the path specified. By default, templates are located in a special subdirectory structure. For the hypothetical outputformat:convertername:templatename -o, --output argument, the directory structure is Converters/outputformat/convertname/templates/templatename/. In addition, Smarty expects to find two subdirectories, templates/ (containing the Smarty template files) and templates_c/ (which will contain the compiled template files). "phpdoc -tb ~/phpdoctemplates -o HTML:frames:default" will only work if the directory ~/phpdoctemplates/Converters/HTML/frames/default/templates contains all the template files, and ~/phpdoctemplates/Converters/HTML/frames/default/templates_c exists.

-ti, --title
Set the global title of the generated documentation

-ue, --undocumentedelements
This option tells phpDocumentor whether or not to suppress warnings about certain objects (classes, methods) that are not documented via a DocBlock comment. Use this to help identify objects that you still need to write documentation for.

phpDocumentor's dynamic User-defined config files The new -c, --config command-line options heralds a new era of ease in using phpDocumentor. What used to require:

phpdoc -t /path/to/output -d path/to/directory1,/another/path,/third/path\
-f /path/to/anotherfile.php -i *test.php,tests/ -pp on -ti My Title -o HTML:frames:phpedit

Can now be done in a single stroke!

phpdoc -c myconfig

What makes this all possible is the use of config files that contain all of the command-line information. There are two configuration files included in the distribution of phpDocumentor, and both are in the user/ subdirectory. To use a configuration file "myconfig.ini," simply place it in the user directory, and the command-line "phpdoc -c myconfig" will tell phpDocumentor to read all the command-line settings from that config file. Configuration files may also be placed in another directory, just specify the full path to the configuration file:

phpdoc -c /full/path/to/myconfig.ini

The best way to ensure your config file matches the format expected by phpDocumentor is to copy the default.ini config file, and modify it to match your needs. Lines that begin with a semi-colon (;) are ignored, and can be used for comments.

7.  phpDocumentor.ini - global configuration options

The phpDocumentor.ini file contains several useful options, most of which will never need to be changed. However, some are useful. The section [_phpDocumentor_options] contains several configuration settings that may be changed to enhance output documentation. For Program Location, the relative path is specified as Program_Root/relativepath/to/file. The prefix "Program_Root" may be changed to any text, including none at all, or "Include ", etc. The [_phpDocumentor_setting] section can be used to specify a config file that should be used by default, so phpDocumentor may be run without any command-line arguments whatsoever! The [_phpDocumentor_phpfile_exts] section tells phpDocumentor which file extensions are php files, add any non-standard extensions, such as "class" to this section.

(Quelle: phpDocumentor Guide to Creating Fantastic Documentation, 05.02.2008)