Description

@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.

@package groups php files together for documentation.

There are two ways a @package tag is parsed:

1. page-level package (defines, functions, includes/requires)

2. 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).

Example

phpDocumentor parses a DocBlock as a page-level DocBlock if it precedes another DocBlock like this:

1. /**
2.  * Page-Level DocBlock example.
3.  * This DocBlock precedes another DocBlock and will be parsed as the page-level.
4.  * Put your @package and @subpackage tags here
5.  * @package pagelevel_package
6.  */
7. /**
8.  * function bluh
9.  */
10. function bluh()
11. {
12. ...
13. }

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.

1. <?php
2. /**
3.  * class bluh
4.  * class-level DocBlock example.
5.  * @package applies_to_bluh
6.  */
7. class bluh
8. {
9.    /**
10.     * This variable is parsed as part of package applies_to_bluh
11.     */
12.    var $foo;
13.    
14.    /**
15.     * So is this function
16.     */
17.    function bar()
18.    {
19.    }}
20. ?>

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