Show
How to use tags in DocBlocksby Copyright 2002, Gregory Beaver Tags ManualWelcome to the phpDocumentor Tags Manual phpDocumentor tags are very similar to tags for the JavaDoc tool for Sun's Java Programming Language. Tags are only parsed if they are the first thing on a new line of a DocBlock. You may use the @ character freely throughout documents as long as it does not begin a new line. An example:
Any tags that phpDocumentor does not recognize will not be parsed, and will be displayed in text flow as if they are part of the DocBlock long description. The example below displays text "tags demonstration @foobar this is silly," and also displays the author as "this tag is parsed, but this @version tag is ignored"
Inline tags display in the text flow where they appear, and are not separated from the description. As of version 1.2, there are several inline tags. The allowed inline tag list is different for tutorials and regular in-code documentation. See phpDocumentor Inline tags for more information. The example below will display the text "this function works heavily with foo() to rule the world" where foo() represents a hyperlink that links to the function foo()'s documentation.
Standard phpDocumentor TagsMost tags can be in the DocBlock of any documentable PHP element (for a definition of a documentable PHP element, see Documentable PHP Elements). Here is a list of the standard tags:
phpDocumentor Packages:Tutorials/Manuals: Package-level:
Files: Classes:
An in-depth look at using phpDocumentor to document PHP Source Code, and phpDocumentor internalsby Table of Contents
phpDocumentor Basics Starting Out From Scratch DocBlocks DocBlock Description details DocBlock Templates Tags Documenting your PHP project Where to begin Elements of the source code that can be documented Dividing projects into packages Advanced phpDocumentor: tutorials and extended Documentation Running phpDocumentor Using the new Web Interface docbuilder Using the old Web Interface phpdoc.php or new_phpdoc.php Using the Command-line tool Running the command-line in MS Windows Running the command-line in unix -c, --config -cp, --converterparams -ct, --customtags -dh, --hidden -dc, --defaultcategoryname -dn, --defaultpackagename -d, --directory -ed, --examplesdir -f, --filename -i, --ignore -is, --ignoresymlinks -it, --ignore-tags -j, --javadocdesc -o, --output -pp, --parseprivate -po, --packageoutput -p, --pear -q, --quiet -ric, --readmeinstallchangelog -s, --sourcecode -t, --target -tb, --templatebase -ti, --title -ue, --undocumentedelements phpDocumentor's dynamic User-defined config files phpDocumentor.ini - global configuration options IntroductionphpDocumentor is the most advanced automatic documentation system written for PHP, in PHP. This package has many features:
phpDocumentor BasicsStarting Out From ScratchThe documentation process begins with the most basic element of phpDocumentor: a Documentation block or DocBlock. A basic DocBlock looks like this:
A DocBlock is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. DocBlocks precede the element they are documenting. Any line within a DocBlock that doesn't begin with a * will be ignored.To document function "foo()", place the DocBlock immediately before the function declaration:
This example will apply the DocBlock to "define('me',2);" instead of to "function foo()":
define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented, see Elements of the source code that can be documented DocBlocksA DocBlock contains three basic segments in this order:
The 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. The Long Description continues for as many lines as desired and may contain html markup for display formatting. Here is a sample DocBlock with a Short and a Long Description:
Optionally, you may enclose all paragraphs in a <p></p> tag. Be careful, if the first paragraph does not begin with <p>, phpDocumentor will assume that the DocBlock is using the simple double linebreak to define paragraph breaks as in:
Here is an example of using <p>
phpDocumentor also supports JavaDoc's DocBlock format through the command-line option -j, --javadocdesc. Due to the non-xhtml compliant unmatched p tag, we highly recommend you avoid this syntax whenever possible
phpDocumentor will convert all whitespace into a single space in the long description, use paragraph breaks to define newlines, or <pre>, as discussed in the next section. DocBlock Description detailsAs of phpDocumentor 1.2.0, the long and short description of a DocBlock is parsed for a few select html tags that determine additional formatting. Due to the nature of phpDocumentor's output as multiple-format, straight html is not allowed in a DocBlock, and will be converted into plain text by all of the converters unless it is one of these tags:
" "(4 spaces) in the PDF converter! The text output is determined by the template options file options.ini found in the base directory of every template. For instance, the options.ini file for the HTML:frames:default template is in phpDocumentor/Converters/HTML/frames/templates/default/options.ini For the rare case when the text "<b>" is needed in a DocBlock, use a double delimiter as in <<b>>. phpDocumentor will automatically translate that to the physical text "<b>". 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.
This will parse as if it were:
New 1.2.0rc1: If you need to use the closing comment "*/" in a DocBlock, use the special escape sequence "{@*}." Here's an example:
This will parse as if it were:
New 1.2.0rc1: The phpEdit tool supports very clever list extraction from DocBlocks, and now phpDocumentor supports the same cleverness. This example:
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.
Again, 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. For in-depth information on how phpDocumentor parses the description field, see ParserDescCleanup.inc DocBlock TemplatesNew for version 1.2.0, phpDocumentor supports the use of DocBlock templates. The purpose of a DocBlock template is to reduce redundant typing. For instance, 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 is distinguished from a normal DocBlock by its header. Here is the most basic DocBlock template:
The text that marks this as a DocBlock template is "/**#@+" - all 6 characters must be present. DocBlock templates are applied to all documentable elements until the ending template marker:
Note that all 8 characters must appear as "/**#@-*/" in order for phpDocumentor to recognize them as a template. Here is an example of a DocBlock template in action:
This example will parse as if it were:
Note that for $_var8 the DocBlock template merged with the DocBlock. The rules for merging are simple:
TagsTags are single words prefixed by a "@" symbol. Tags inform phpDocumentor how to present information and modify display of documentation. All tags are optional, but if you use a tag, they do have specific requirements to parse properly. A list of all possible tags in phpDocumentor follows:
In addition, tutorials 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. See inline {@id} and inline {@toc} for detailed information 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.
<refentry id="{@id}"> <refsect1 id="{@id mysection}"> <refsect2 id="{@id mysubsection}"> </refsect2> </refsect1> </refentry> For an in-depth look at phpDocumentor tags, read phpDocumentor tags, and for an in-depth look at inline tags, read phpDocumentor Inline tags. Documenting your PHP projectWhere to beginBefore you begin documenting your PHP project, you might want to try a test run on your undocumented source code to see what kind of information phpDocumentor will automatically extract from the source code. phpDocumentor is designed to make the task of documenting minimally redundant. This means less work, and better, up-to-date documentation with less effort than it used to take. phpDocumentor is a great tool, but it will not write good documentation for you. Please read the phpDocumentor Guide to Creating Fantastic DocumentationElements of the source code that can be documentedDividing projects into packagesTo understand the role of packages and how to use @package, it is important to know 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 their 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 (but no constants in PHP). A single class packages together related functions and variables to be re-used. phpDocumentor defines package in two ways:
For more information on page-level versus class-level packaging, see Procedural Elements 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. Advanced phpDocumentor: tutorials and extended DocumentationphpDocumentor developers have received a number of requests to allow 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. What is the solution? 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:
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. For an in-depth look at how to use tutorials, read phpDocumentor Tutorials Running phpDocumentorThere are two bundled ways of invoking phpDocumentor, the command-line phpdoc, or the web interface phpdoc.php/new_phpdoc.php. Using the new Web Interface docbuilderThe new web interface requires a working installation of PHP with a web server, and must be accessible from the document root. Docbuilder is the creation of Andrew Eddies, and it combines some slick formatting with the functionality of the old web interface. The docbuilder interface can be accessed via index.html in the install directory of phpDocumentor, or the docbuilder subdirectory. Using the old Web Interface phpdoc.php or new_phpdoc.phpIn order to use the web interface, there are a number of factors that must be set up before anything else can occur. First, you need a working web server with php (it had to be said). This manual will not assist with that setup. Next, the phpdoc.php or new_phpdoc.php file needs to be accessible by the webserver. In unix, place a symbolic link using ln -s to the desired interface into the public html directory. Security is always an issue with the internet. Do not place phpDocumentor into the web server publicly available path on a server connected to the internet. Make sure that phpDocumentor will not have the power to overwrite ANY system or user files.Note that since the webserver runs as user nobody in unix, the generated files will be owned by nobody. The only way to change this is to either run phpDocumentor from the command-line or to add a chuser wrapper around httpd. We do not recommend using a chuser wrapper or running phpDocumentor as root. It is much easier and safer to use a config file (see phpDocumentor's dynamic User-defined config files) from the command line. Using the Command-line toolRunning the command-line in MS WindowsRunning phpDocumentor from the command-line is fairly straightforward, even in windows. It is recommended to use the web interface in windows, from a non-publicly accessible server root, as none of the permissions issues exist that exist in unix. However, to use phpDocumentor from the command line is possible. First, put the location of php into the system path, then type: C:\>php-cli C:\path\to\phpdoc\phpdoc [commandline] An alternative is to edit the phpdoc.bat file, and place phpdoc in the path, then you can run phpdoc as a normal command. Running the command-line in unixRunning the command-line tool phpdoc is very easy in unix: .\phpdoc [commandline]
-c, --configUse 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, --converterparamsThis 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, --customtagsUse 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, --hiddenUse this option to tell phpDocumentor to parse files and directories that begin with a period (.) -dc, --defaultcategorynameThis 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, --defaultpackagenameUse 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, --directoryThis 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, --examplesdirThe -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, --filenameThis 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.
-i, --ignoreUse 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/".
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.
-is, --ignoresymlinksUse 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-tagsUse 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, --javadocdescUse 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, --outputUse this required option to tell phpDocumentor which Converters and templates to use. In this release, there are several choices:
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, --parseprivateBy 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, --packageoutputUse 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, --pearUse this option to parse a PEAR-style repository. phpDocumentor will do several "smart" things to make life easier:
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, --quietThis 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, --readmeinstallchangelogThis 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:
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, --sourcecodeThis 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, --targetUse 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/. The class file for convertname should be in the convertname/templates directly, right beside your templatename directory/ies. 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, --titleSet the global title of the generated documentation -ue, --undocumentedelementsThis 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 filesThe 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. Be sure to put in your config file all the runtime options you need, because all other command-line arguments are ignored if you use a config file.phpDocumentor.ini - global configuration optionsThe 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.
Documentation generated on Tue, 06 Dec 2011 07:15:41 -0600 by phpDocumentor 1.4.4 |