Re: PEAR API docs

Hi Lorenzo, This is a very frequently asked question, and is answered in the FAQ file that is in the phpDocumentor docs :). The short answer is: This is a warning, you can ignore it The long answer is: phpDocumentor documents two different kinds of packages with the same tag. -Classes -Procedural Elements The top-level elements are a Class and a File. This is very confusing, and will be reworked in version 2.0. The problem with version 1.x is that it is possible to put two classes in the same file that are in different packages: <?php define("CLASSCONSTANT", 6); define("HITCHHIKER", 42); define("OTHER", -29); /** * @package one */ class one {} /** * @package two */ class two extends one {} ?> To which package do the series of define statements belong? phpDocumentor can't automatically determine that they belong to either package one or two, and will assume they belong to the default package. If you add in a @package tag like this: <?php /** * File myfile.php * * Contains two utility classes and constants for package one * @package one */ define("CLASSCONSTANT", 6); define("HITCHHIKER", 42); define("OTHER", -29); /** * @package one */ class one {} /** * @package two */ class two extends one {} ?> phpDocumentor will raise a warning because the documentation will be attached to the define constant CLASSCONSTANT instead of to the file, and defines can't have @package tags (for this exact reason, to help catch errors), there is no automatically determine whether the docblock belongs to the file or the define without a new tag (which will be added in version 2.0, we can't do this without breaking BC). However, if you DO want to document a specific file, there is only one way to do it in phpDocumentor 1.x, in this format: <?php /** * File myfile.php docblock * * Contains two utility classes and constants for package one * @package one */ /** * First constant docblock */ define("CLASSCONSTANT", 6); define("HITCHHIKER", 42); define("OTHER", -29); /** * @package one */ class one {} /** * @package two */ class two extends one {} ?> To put the last code fragment in words, the File documentation is the ONLY Procedural DocBlock that can contain a @package tag. File documentation is the first docblock in the file if and ONLY if it is immediately followed by another docblock. Definitions: DocBlock -> /** */ Procedural DocBlock -> any DocBlock preceding a define, include, function, global variable, or a file-level docblock Class DocBlock -> any DocBlock preceding a class, var or method (or PHP 5 const, interface) File-level DocBlock -> the first DocBlock in a file, if it is followed by a Procedural or a Class DocBlock Regards, Greg -- phpDocumentor http://www.phpdoc.org Lorenzo Alberton wrote:

On Tue, 15 Jul 2003 09:13:52 -0700, Joshua Eichorn wrote:

I updated my API docs of PEAR, it now includes the majority of PEAR packages including BETA and Development ones. The docs are available at: http://phpdorks.net/docs/api/ -joshua eichorn

Hi Joshua, thanks for your API docs, they're extremely useful for us developer to spot php-doc errors. There's one thing that I'm wondering about, though, and IIRC it's the same thing Jesus had already asked some time ago, but I haven't seen a reply to that question. In almost every file, there's a pair of warnings like these: Warning on line ### - no @package tag was used in a DocBlock for class XXX

Warning on line ### - no @package tag was used in a DocBlock for file /usr/share/pear/XXX They're often duplicated, the only difference being the line #, one is at the beginning of the class, and the other one at the end. Since the @package tag _is_ used in most of those files, I wonder what we're doing wrong... is it placed in the wrong position? Or is it a phpDocumentor bug? Best regards, Lorenzo