documentation for a package in php?

Question

so in a folder PayPal i've got multiple classes for using their API.

i want to make a documentation for how to use all the classes in a sequential way. so here is my questions:

1. how do i create a package for them? cause above each class i used phpdoc tag @package PayPal. is a package in php just a folder?

2. where do i put documentation for the package? there are best practices for this? a file in the folder named ...?

3. how to put class- or package-specific examples, eg. step 1 bla bla, step 2 bla bla? thanks!

Answer 1

You can have the same package annotations for multiple classes in separate files. PHP Documentor will collect them and when creating the API Docs, group files with the same package annotation.

For instance http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate.php

/**
 * @category   Zend
 * @package    Zend_Validate
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Validate implements Zend_Validate_Interface

and http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate/Alnum.php

/**
 * @category   Zend
 * @package    Zend_Validate
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Validate_Alnum extends Zend_Validate_Abstract

Both are separate files, but belong to the Zend_Validate package. Thus, on http://framework.zend.com/apidoc/core/ you can find them grouped in the same package.

You can also have subpackages to group additional classes below a normal package. For instance http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate/Sitemap/Lastmod.php

/**
 * Validates whether a given value is valid as a sitemap <lastmod> value
 *
 * @link       http://www.sitemaps.org/protocol.php Sitemaps XML format
 *
 * @category   Zend
 * @package    Zend_Validate
 * @subpackage Sitemap
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Validate_Sitemap_Lastmod extends Zend_Validate_Abstract

See the above linked API docs to see how it shows when generated.

You do not document package annotations. The annotation is just used to logically group class or files that conceptuially belong to together. If you want to have a package description, write it either into the most appropriate file of the package or create a separate file and give it the same annotation as the other files/classes in that package have.

For examples of usage to packages, you the example annotation to link files which contains examples or simply write them inline with code tags in the DocBlocks. If you are using a separate file to document your packages, you could insert them there.

/**
 * MyLib
 *
 * Files under the MyLib package do foo and bar. They are baz.
 * 
 * Usage Examples of MyLib classes
 * <code>
 * $foo = new Foo;
 * $foo->doSomething()
 * </code>
 *
 * @package MyLib
 *
 * @example /some/path/to/an/example/file 
 */