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 (this is where globally-scoped functions and constants would get their "package" from), and in the docblock of every class. 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_phpDocumentor.howto.pkg.html#using.command-line.defaultpackagename
(I was including more URLs, but stackoverflow won t let me post more than one...)
