How to fix “Hook implementations should not duplicate @param documentation.”?

Question

I am using PhpStorm to experiment with cleaning up my code in a custom module. For the following function, I'm getting this warning:

Hook implementations should not duplicate @param documentation.

/**
 * Implements hook_field_widget_form_alter().
 *
 * @param array $element
 * @param array $form_state
 * @param array $context
 */
function mymodule_field_widget_form_alter(&$element, $form_state, $context) {
  if ($context['widget'] instanceof \Drupal\text\Plugin\Field\FieldWidget\TextareaWidget) {
    $element['#after_build'][] = '_mymodule_remove_textarea_help';
  }
}

What should I do to fix this? I thought I needed to delete the @param comments, but when I do that, PhpStorm complains that I don't have any param comments.

Answer 1

The problem is that if you're implementing a hook and you don't need to write more than this:

/**
 * Implements hook_field_widget_form_alter().
 */

Because you will have all the information in the hook_field_widget_form_alter() definition, so just write always in the hooks implementations only this:

/**
 * Implements hook_hook_name().
 */

In your case:

/**
 * Implements hook_field_widget_form_alter().
 */
function mymodule_field_widget_form_alter(&$element, $form_state, $context) {
  if ($context['widget'] instanceof \Drupal\text\Plugin\Field\FieldWidget\TextareaWidget) {
    $element['#after_build'][] = '_mymodule_remove_textarea_help';
  }
}

Answer 2

Adding an answer for posterity; as per Clive's comment:

You need to turn off the built in PHPStorm inspection that checks for "Missing PHPDoc Comments", then you can safely delete your @param blocks.

Answer 3

As others have said, you need to set the PHPStorm config to treat your project as a Drupal project.

Second to that, get up and running with Coder.

Once you have those packages installed, you can wire them up in PHPStorm and set your standards system accordingly or just run the reports from command line. This will make your environment more in-line with the Drupal coding standards instead of the general ones that ship with PHPStorm out of the box config.