Re: phpDocumentor Docs for most of PEAR

Hi Jesus, Jesus M. Castagnetto wrote:

Using the logic of your parser, if I have a script bar.php form the package Cool_Foo.php that includes first Foo.php (that has @package Cool_Foo) and then also includes Math/Stats.php (that has @pacakage math_Stats), would that generate and error? What would be the package automatically assigned to bar.php? Cool_Foo? or Math_Stats?

I don't quite understand your example. is Cool_Foo.php a file or a package? phpDocumentor will make assumptions about packaging successfully, unless there is a name conflict. The main problem with the language of PHP is that there are two methods of "packaging" elements built into the language: files and classes. phpDocumentor 1.x assumes that procedural elements are not necessarily related to the class elements. For instance: <?php /** * This is the documentation for the function that follows */ function func() { } /** * This is the documentation for first class * @package firstpackage */ class first { } /** * This is the documentation for second class * @package secondpackage */ class second extends first { } ?> The file above contains two classes in different packages (first and second. To which package does function func() belong? There is no way to automatically determine the author's intention in this case, a flaw in the design of the @package tag in the original PHPDoc This question is answered in phpDocumentor 1.x by separating procedural packages from class packages. This is very confusing simply because procedural and class elements can co-exist within the same file legally in php.

Also the warnings about @package not being in a docblock seems to me spurious, as (again) following the javadoc style, is usually put right before the class contained in a file, not by itself.

The assumption you are making is that all files only contain classes, and that every file contains only 1 class in 1 package (or many classes in 1 package). This is not necessarily the case, and phpDocumentor groups procedural elements into separate packages (file-level or page-level) from classes (class-level package). In other words, in the real world outside of PEAR, it may be useful occasionally, to summarize the purpose of a file (and in the future, to document the $_REQUEST parameters it expects to receive). This is done in a file-level docblock. <?php /** * This file accepts input from a web browser * * The file contains these programming elements and does * this stuff, and so on. * @filesource * @package Webstuff */ ?> Let's say the first element in a file is a function (logical possibility). <?php /** * This file accepts input from a web browser * * The file contains these programming elements and does * this stuff, and so on. * @filesource * @package Webstuff */ function myfunc() { } ?> Now, this docblock has become attached to the function as its documentation, and is no longer associated with the file! What to do? phpDocumentor's solution is to require file-level documentation to be the first docblock, and to immediately be followed by the documentation for the first element in the file, as in: <?php /** * This file accepts input from a web browser * * The file contains these programming elements and does * this stuff, and so on. * @filesource * @package Webstuff */ /** * function myfunc's documentation */ function myfunc() { } ?> If that first docblock is not found, phpDocumentor raises a warning (not an error), telling you that it has made an assumption about packaging. The assumption is that if 1 @package tag is present in the file, say: <?php /** * @package Math_stats */ class Math_stats {...} ?> that the entire file is in package Math_stats. However, this assumption is an assumption and so may be incorrect. phpDocumentor simply warns you that you did not supply concrete instructions that "yes, this file is a part of package Math_stats, and all procedural elements are also a part of package Math_stats" if phpDocumentor was only needed to document PEAR, this would be a ridiculous warning. Of course all PEAR projects must conform to PEAR coding standards, which includes 1 class per file. phpDocumentor could simply raise an error if more than 1 class were in a file, or more than 1 @package tag used in a file, but when we designed the current incarnation of phpDocumentor, there was already a tool out there with these restrictions, and it literally doesn't work at all for about 50-60% of real-world non-PEAR php projects. This is not to criticize PEAR, if we didn't think PEAR was going in a good direction, phpDocumentor would be a separate project entirely, and not even have the peardoc2 converter. It's just a fact of php design that until php 5 and the package question is resolved, packaging will be unclear.

For example phpDocumentor says: Macromolecule_PDB.php Warnings: Warning on line 83 - no @package tag was used in a DocBlock for file /usr/share/pear/Science/Chemistry/Macromolecule_PDB.php Line 83 is the last line in that file.

in a file containing no docblocks, the non-presence of the page-level docblock will not be detected until the end of the file. The line number is a problem that will be resolved in phpdocumentor 2.0, as the warning message is quite clear.

And the correspoding lines say at before the class definition are: ... require_once "Science/Chemistry/Macromolecule.php"; require_once "Science/Chemistry/Residue_PDB.php"; /** * Represents a PDB macromolecule, composed of several * Science_Chemistry_Residue_PDB objects * * @author Jesus M. Castagnetto <jmcastagnetto@php.net> * @version 1.0 * @access public * @package Science_Chemistry */ class Science_Chemistry_Macromolecule_PDB extends Science_Chemistry_Macromolecule { ... I would consider that a bug in phpDocumentor not to notice the @package there, and only force it to be at the top of the file in a *separate* documentation block, e.g.: /** * @package Science_Chemistry */

This is not a bug, the @package tag is noticed and applied to the class, but phpDocumentor does not assume that a file will contain no procedural elements, and even many PEAR packages use define(). Almost all use include_once().

... etc ... Just minor annoyances on great documentation tool.

I/we appreciate this, and now that I've spent an entire email explaining the choices made in the 1.x line, let me describe the changes that will happen in 2.x :) First of all, to fix this problem requires a minor but significant BC break with PHPDoc and with phpDocumentor 1.x. phpDocumentor 2.0 will offer many new ways of packaging elements together, by allowing a plugin module specifically for determing package. The plugin module will process every top-level element (i.e. class, file. class properties/methods are part of the class package, procedural elements are part of a file) and based on the path to the file containing it, and any docblock found, will determine the package that it should belong to. This means that, for instance, the --pear=on command-line switch could silently select a PEAR packaging algorithm that determines packaging based solely on classes, and expects PEAR coding standards. Other packaging methods could be chosen on the command line (including a backwards-compatible method that raises all the old familiar warnings). The biggest change will be in the determination of a page-level docblock. A new tag @filesummary (or something along those lines) will be required to identify a file-level docblock. This will also make it clearer to users unfamiliar with phpDocumentor what purpose that documentation segment serves. I would like to move away from using docblock tags to determine packaging altogether. I think it's a stupid idea in the first place :). The natural packaging of PHP is the file, and directory, unless code is stored in a database repository. A current feature request involves the ability to document code stored in just such a repository. Packaging should be determined by directory, as it is in java, and then tags can be used to sub-group elements together. Of course, this solution is also a personal opinion, and having a package algorithm module will allow even the most disgruntled users to solve the way phpDocumentor groups elements together in the best way for their specific projects. Hope this helps to elucidate the problems we're trying to deal with and offers a bit of solution. For now, just remember: these are only warnings, not errors. in phpDocumentor, a warning is just that, not the end of the world. Regards, Greg -- phpDocumentor http://www.phpdoc.org