Packages

The java way

The first way, coming from java is quite simple : a package is a directory containing source code.

Advantages

Packages are formed automatically, without extra work from developers (no need of @package tags).
Depth of package hierarchy is not limited.
The association between a directory and a package permit to have package comment files, in general called package.html, located in the package's directory.

Inconvenients

As a package is stuck to a directory, code elements of a package must be in files located in the same directory. This can be an annoying limitation.

Usage in phpSimpleDoc

This definition of package is handled by the 'default' documentor implementation.
To generate documentation for a project using this definition of package, you must set the related directives in the user directives file (.ini) :

documentorType in section essential must be equal to default.
topPackageName in section essential must be filled.
topPackageName is used in conjunction with option sourceDir (also in section essential).
This field is necessary because phpSimpleDoc doesn't work exactly like javadoc.
A typical java project is organized like this :
```
	project1
	|-- bin
	|-- lib
	`-- src
		`-- project1
	
```
Here, the effective sources are located under project1/src/project1, and the top-level package is called 'project1' ; in java, the source code MUST be located under a directory having the same name as the top-level package, and this generally obliges to have a supplementory level of directory.

The field topPackageName was introduced to avoid this inconvenient. The source code can be directly located in src/.
In this case, directive sourceDir must point to project1/src.
packageCommentFile in section secondary can be filled ; the default for this directive is package.html.
It corresponds to the name of files containing the package comments (this file must be located in the directory associated to the package, in the source tree).
For example, In phpSimpleDoc source code, 1.package.html is used, so when browsing a source code directory, It's easy to make the difference between files containing source code and auxiliary files.

The Zend Framework way

Packages are formed using two tags in doc domments : @package and @subpackage.
The definition of a package is here : code elements that share the same @package or @subpackage tags.

Advantages

Code elements belonging to a given package don't need to be located in the same directory. This possibility is used in many software projects.
For example Zend Framework has a Zend_Log package. Part of the source code files is :
```
	Zend
	  |-- Log
	  |   `-- Exception.php
	  `-- Log.php
	
```
Code elements in Zend/Log.php and in Zend/Log/Exception.php have in their doc comment the tag @package Zend_Log, so they belong to the same package although they are located in different directories. This way to organize the code is not possible using the java way.

Inconvenients

To correctly form their packages, programmers must write the @package and @subpackage tags for each code elements. If they forget, code elements remain unpackaged.
Depth of package hierarchy is limited to two levels. This could be fixed using other tags (@subsubpackage for example).
There is no way to have package comments ; this could be done with extra convention, but this is currently not done.
(Example of extra convention : place files package.html anywhere in the source code, and use a @package tag in these files, to associate the comment to a package. The code documentor could then understand the association.)

Usage in phpSimpleDoc

This definition is handled by the 'zendlike' documentor implementation.
To generate documentation for a project using this definition of package, you must only set one option in the user directives file (.ini) :

documentorType in section essential must be equal to zendlike

If a code element is found without @package tag, it is put in a package called 'default'.

Namespaces

The introduction of namespaces (php 5.3 and higher) will probably give us a way to form packages from namespaces.
This is not (yet) implemented in phpsimpledoc.