Defining namespaces in phpDoc syntax

Question

Can anyone tell me what the correct way to define php namespaces in phpDoc syntax is? Or, is @package deprecated in phpDoc, since namespaces more or less define a package?

If there is none, is there a common way to document the namespaces a document is in?

Answer 1

phpDoc doesn't have a concept of namespaces but you can (and probably should) use @package for it.

You might take a look at the phplint documentation to see how they're formatting namespaces.

Answer 2

@package Should be used in every docblock of every file in your project, you can also use @subpackage. @package is not deprecated, and would be the correct way to define your namespaces.

Answer 3

You can take a look at DocBlox; this is a API Documentation Generator that supports namespaces.

And to more clearly answer your question: as far as I have encountered are packages considered Deprecated due to the invention of Namespaces. If you read the PSR-0 specification you will see that it tries to provide the Package as second part of a namespace; first being vendor.

Answer 4

The phpDoc documentation says:

The @package tag can be used as a counterpart or supplement to Namespaces. Namespaces provide a functional subdivision of Structural Elements where the @package tag can provide a logical subdivision in which way the elements can be grouped with a different hierarchy.

If, across the board, both logical and functional subdivisions are equal is it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.

https://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html