phpDocumentor phpDocumentor
[ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ]
Prev Next

@package

Specify package to group classes or functions and defines into

by Gregory Beaver
Tag Documentation written by cellog@php.net
Copyright 2002, Gregory Beaver
(phpDocumentor 0.1+)
@package packagename

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.

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:

  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

Prev Up Next
@name phpDocumentor tags @param

Documentation generated on Tue, 06 Dec 2011 07:15:49 -0600 by phpDocumentor 1.4.4