Prev | Next |
@package can only be used to document procedural pages or classes.
Packages are used to help you logically group related elements. You write classes to group related functions and data together, and phpDocumentor represents the contents of files (functions, defines, and includes) as "Procedural Pages." A package is used to group classes and procedural pages together in the same manner that a directory groups related files together.
If found in a page-level DocBlock, packagename specifies the package that all functions, includes, and defines in the php file belong to. If found in a class-level DocBlock, packagename specifies the package that the class belongs to.
If not present, a class's package is set to default, or the value of the -dn command-line switch, even if the page-level package is set to another value. This may be changed by the command-line option -dn or --defaultpackagename. PACKAGES MUST BE ONE WORD WITH NO SPACES OR NEWLINES CONTAINING ONLY LETTERS, DIGITS, and "_", "-", "[" or "]"@package groups php files together for documentation.
There are two ways a @package tag is parsed:
page-level package (defines, functions, includes/requires)
class-level package (class, all its variables and methods)
If a file contains functions and defines, they will be packaged by a page-level DocBlock. A page-level DocBlock is a DocBlock at the top of a file that precedes another DocBlock. In other words, it is not paired with any phpDocumentor element (include, function, define, class, class function, class variable).
phpDocumentor parses a DocBlock as a page-level DocBlock if it precedes another DocBlock like this:
A page is documented as a procedural page if it is parsed, regardless of its content (NEW in 1.0).
A class-level DocBlock is any DocBlock that precedes a class definition in a php file.
If no @package tag is specified, the package named "default" will be used, with one major exception. If a class extends a parent class that has a @package tag, it will inherit the package from the parent class. This can be very useful in small projects. HOWEVER, it is highly recommended that a @package tag is used before every class that should have that package to avoid name collisions. What is a name collision? If you are documenting two related but separate packages, and both packages contain classes with the same name. For example, the tests package included with phpDocumentor contains several files used to verify the eradication of bugs from phpDocumentor. Several of these files contain classes with the same name as classes in phpDocumentor. phpDocumentor cannot determine the correct parent class automatically and will not inherit package at all to avoid a wrong guess. WE HIGHLY RECOMMEND THAT YOU USE @package IN THE DOCBLOCK OF EVERY CLASS OR PROCEDURAL PAGE YOU WISH TO BE IN A PACKAGE.
Elements can also be grouped into subpackages using @subpackage
See also @subpackage
Prev | Up | Next |
@name | phpDocumentor tags | @param |