Packages

The java way The Zend Framework way Namespaces

A package can be defined as : a way to group code elements.
This notion is absent from PHP, and different ways to form packages can be found.
phpSimpleDoc currently supports two different ways to form 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.
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, placed 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 is handled by the 'default' documentor implementation.
To generate documentation for a project using this definition of package, you must set the related options in the user command 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' ; 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, option sourceDir must point to project1/src.
packageCommentFile in section secondary must be filled ; the default is package.html.
It corresponds to the name of file containing the package comment (this file must be located in the directory associated to the package, in the source tree).
For example, I use 1.package.html, so when I browse a source code directory, I easily 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.
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 command 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.

<< Syntax of doc comments

Forum : Répondre à cet article