What is the purpose of these PHPDOC properties?

Question

In general, the PHPDOC properties are self-explanatory, but I'm having hard time understanding these:

@category - what is this exactly?

@package - could some one provide me examples about the usage of this property?

Answer 1

@category

The @category tag is used to organize groups of packages together.

This is directly applicable to the XML:DocBook/peardoc2 Converter, and can be used by other converters. Other Converters packaged with phpDocumentor ignore the category, but this may change in future versions. It is also possible to dynamically specify category using the -dc, --defaultcategoryname command-line switch

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.category.pkg.html

@package

@package can only be used to document procedural pages or classes.

Packages are used to help you logically group related elements. You write classes to group related functions and data together, and phpDocumentor represents the contents of files (functions, defines, and includes) as "Procedural Pages." A package is used to group classes and procedural pages together in the same manner that a directory groups related files together.

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.package.pkg.html

Answer 2

The package tag is the key organizing tag that you use in your code. When phpDocumentor generates the docs, it collects elements into the packages that you set. In some cases, you might choose to only use one package name (@package MyPackage) for your entire codebase, such that all files, classes, etc, will appear in that package's docs.

However, if you choose to organize things more modularly, you could have all web-facing procedural files in one package (@package Webpages), all database-facing classes in a package (@package DatabaseHandlers), all utility classes in a package (@package Utilites), and on and on.

The key thing to remember about @package is that it's your avenue for organizing the docs... it has nothing to do with how the code executes. Now, obviously you're more likely to want to organize the docs based on how you conceptually organize the pieces of your app in your head, so that in this sense, "package" would feel like it's organizing the code... But in the end, the package tag is all about how you want phpDocumentor to organize the docs.

As for the category tag, I don't believe any output converters utilize that except the one(s) that matter to the PEAR project. Category is used to collect sets of packages into one large bundle. But again, this is only relevant to PEAR, as far as what capabilities are already baked into the output converters. You can ignore this tag if you want to... you cannot ignore the package tag, because it is core to how phpDocumentor organizes the docs.

Now, as to examples of using @package, there are some in the manual, as seengee already mentioned. Long story short, you need a package tag in the file-level docblock of every file, in the docblock of every class, and in the docblock of every non-class function (i.e. global-scoped functions). If you don't provide package values for these code elements, phpDocumentor is forced to just dump them all into a "default" package.

Last point... if you don't care about organizing your code into various packages, and don't want to edit all your files to add the @package tags, you can instead use the -dn runtime argument to set a default package name [1]. This tells phpDocumentor to use the package name you provide in that argument for all "unpackaged" code elements that it wants a package name for. There is also a -dc argument to set a default category name, but that's far less critical a need as far as phpDocumentor is concerned.

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial%5FphpDocumentor.howto.pkg.html#using.command-line.defaultpackagename

(I was including more URLs, but stackoverflow won't let me post more than one...)