In phpDoc, is it neccessary to define parameter type?

Question

an old fashioned example:

/**
 * @param string $a - test parameter
 */
public function test($a)
{
}

but now that Php has types, I would write:

/**
 * @param $a - test parameter
 */
public function test(string $a)
{
}

since it has a parameter, so adding "string" to phpdoc is verbose.

Answer 1

"Necessary" depends on what you're using to parse the annotation (if anything)*

If this is PHPDocumentor itself, you'll want to stick with the standard that it prescribes. Even if it works without the type now, there's no guarantee that a future version will, and as mentioned in Alex Howansky's answer, the type is currently defined as mandatory. From their manual:

With the @param tag it is possible to document the type and function of a single argument of a function or method. When provided it MUST contain a Type to indicate what is expected; the description on the other hand is OPTIONAL yet RECOMMENDED in case of complicated structures, such as associative arrays.

PHPStorm (at least the version I have in front of me) acts a bit strangely if you leave out the type-hint in a parameter. If I use

 * @param $a Some useful comment about my parameter

then I get a warning about Undefined class Some. Apparently it's taking the first word other than the @param annotation and the variable name, and assuming that's the type. I can't find a reference to this behaviour in the phpdoc manual (providing the type after the variable), so that could itself be non-standard. Interestingly, if the first character after the variable name is a hyphen (as in the example in your question), then the warning is supressed.

I've seen a lot of code recently that leaves out the annotations entirely, and relies on the language's internal type-hinting (both parameter and return) to do the job. This is perfect, as long as you don't need to add a description to any of them. PHPStorm will warn you about missing parameter annotations the moment you provide any (but not all) of them, which means if you want to provide a comment for one then you'll need to add the rest, commented or not.

You mention verbosity in your question, and if all you're concerned about is human readability then by all means leave out the type. Phpdoc itself has a standard, but you're absolutely not bound by it. It's your code, ultimately. But if you're shipping a package that other developers might use, or if any of your toolchain (from IDE, through static analysis, to documentation generation itself) aren't happy with the non-standard usage, then you'll have to weigh up the decision again. Either way it comes down to whether you're the only one (person or machine) reading your code; if you're not, then stick with the standards, even if it means typing a few extra characters.

--

* This can include things that actually do affect the way the code runs - PHP allows you to fetch these annotations with the getDocComment methods in the Reflection API. Use-cases for this tend not to include @param annotations (more often it'll be something package specific like Doctrine's ORM annotations), which are almost exclusively used for documentation, but I don't want to over-generalise and say that this can't have an effect on your code's actual functionality.

Answer 2

The phpDocumentor docs state that the Datatype field is required for @param. Those docs are quite old, but I would expect apps which consume tags to still abide by that requirement. Lately, I've tended to skip the @param tag completely when I have an explicit typehint present.

PHPCS will alert if you leave it out but have a typehint, like in your example:

/**
 * @param $arg The arg.
 */
public function foo(int $arg) {

PHPStan will alert if you have a @param tag type and a typehint that don't match, like this:

/**
 * @param string $arg The arg.
 */
public function foo(int $arg) {