This suggestion is based on an observation in Drupal 7.
It is becoming less of a problem with more and more code being OOP (e.g. moving to Drupal 8), but it might still apply to some people or more, for some time or longer.

Problem: The framework (or CMS) forces a specific parameter signature for functions with a specific role.
In Drupal 7 these are hooks, theme functions, form builder functions, etc.

The IDE does not know this, and complains about unused parameters.

For a class method overriding an interface method, it does not care if parameters are unused, because it understands that the parameters are required. But for procedural, this does not work.

The official way to document this in Drupal 7 is "Implements hook_foo()". But this is too much of a Drupalism to suggest support by the IDE or phpDocumentor. Also, it only applies to hooks, not to theme functions or form callbacks.

So I am going to suggest an @implements doc tag for functions, methods and closures - equivalent to the native "implements" statement, but on function level.

The @implements tag would indicate that the function has the same (or weaker) signature as the one it implements, in the same way that a class method must have the same (or weaker) signature as the interface method it implements.

An IDE that understands this could

• Complain about signature mismatch.
• Stop complaining about unused parameters in the implementing function.

This is how it would look like:

function hook_eat(Food $food) {}

/**
 * @implements hook_eat()
 */
function my_eat(Food $food) {
  // No need to actually use the $food parameter.
}

/**
 * @implements hook_eat()
 */
$f = function(Food $foo) {
}

class C {
  /**
   * @implements hook_eat()
   */
  static function eatQuietly(Food $foo) {}
}

Old discussion on drupal.org: https://www.drupal.org/node/983268 (I am not promising anything about whether the Drupal community will pick this up)

Doxygen has something like it, but I don't quite understand how it is meant to be used..
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdimplements

EDIT: I just realize there is a github user with this name :)
Code formatting of @implements helps.