Only allow useful @param and @return annotations

[nicwortel]

This disallows the use of individual @param and @return annotations when PHP type declarations already provide sufficient information.

Instead of requiring that all parameters and the return type are documented:

/**
 * @param string $stringA
 * @param string $stringB
 * @param int[]  $numbers
 *
 * @return void
 */
public function documentAllTheThings(string $stringA, string $stringB, array $numbers): void
{
}

...this allows (and even enforces) that only "useful" annotations are used:

/**
 * @param int[] $numbers
 */
public function onlyUsefulAnnotations(string $stringA, string $stringB, array $numbers): void
{
}

This way, we can keep our codebase "clean" with only the docblock annotations we really need.

The violations can be automatically fixed by CodeSniffer using the vendor/bin/phpcbf command, but that may leave behind some trailing blank lines in docblocks, so some manual care is recommended.

[denniscoorn]

🦄