I created a PHP class in PhpStorm and allowed the IDE to auto-generate the DocBlock for the class. It included a package tag that exactly matched the namespace of the file as follows:
<?php
namespace frontend\controllers;
/**
* Class MethodController
* @package frontend\controllers
*/
class MethodController extends BaseRestController
{
}
I don't presently care to generate PHPDocumentor output, but I may want to at some point, so I would like to understand how @package is used. What surprises me is the message that PHP_CodeSniffer provided for this tag:
[phpcs] Package name "frontend\controllers" is not valid; consider "Frontendcontrollers" instead
Do I need to create some sort of table of contents to satisfy PHP_CodeSniffer?
Another perplexing twist is this quote from the PHPDoc website:
If, across the board, both logical and functional subdivisions are equal is it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.
If I understand this correctly, there is no benefit in making the package exactly equal to the namespace. Why did PhpStorm provide this tag?