Ignore specifc sniffs when adding additional parameters to interface methods

I've updated Step 2: Prepare the new signature in the documentation as part of this change. Specifically, I replaced the broad phpcs:disable Drupal.Commenting with targeted phpcs:ignore annotations for:

Drupal.Commenting.DocComment.TagGroupSpacing

Drupal.Commenting.FunctionComment.ParamNameNoMatch

This ensures that we only suppress the necessary sniffs and maintain all other coding standards. The change is in line with the recommendations discussed in #3531685 Proposed Resolution

https://www.drupal.org/about/core/policies/core-change-policies/how-to-d... →

I've actually gone further in 🐛 Fix PHPStan arguments.count error Active and proposed that we change the standard to move the @todo and @see to the correct part of the docblock. This achieves several things:

1. It has better readability.
2. It follows our existing documentation standards.
3. It allows us to remove an entire phpcs:ignore from every single parameter and typehint addition of this sort.
4. It allows for the possibility of multiple parameters being added to a method, and for listing them clearly for the developer.

Here's an example from that issue:

  /**
   * Gets sorted plugin definitions.
   *
   * @param array[]|null $definitions
   *   (optional) The plugin definitions to sort. If omitted, all plugin
   *   definitions are used.
   * phpcs:ignore Drupal.Commenting.FunctionComment.ParamNameNoMatch
   * @param string $label_key
   *   (optional) The key to be used as a label for sorting.
   *
   * @return array[]
   *   An array of plugin definitions, sorted by category and label.
   *
   * @see https://www.drupal.org/project/drupal/issues/3354672
   *
   * @todo Uncomment the new $label_key method parameter before drupal:12.0.0.
   */
  public function getSortedDefinitions(?array $definitions = NULL /*, string $label_key = 'label' */);

The current MR appears empty, so no credit is granted for @immaculatexavier.

A sample for the documentation page might be something like:

 /**
   * Returns sample data.
   *
   * phpcs:ignore Drupal.Commenting.FunctionComment.ParamNameNoMatch
   * @param string $added_parameter
   *   The new parameter being added.
   *
   * @return array[]
   *   The sample data.
   *
   * @see https://www.drupal.org/project/drupal/issues/3354672
   *
   * @todo Uncomment the new $added_parameter method parameter before drupal:12.0.0.
   */
  public function getSampleData(/* string $added_parameter = '' */);

xjm → changed the visibility of the branch 3531685-ignore-specifc-sniffs to hidden.

Fix link in issue summary

The proposal in #8 looks better. I have updated the 'how to' doc with that example as well as the issue summary. I think everything is done here.

Setting to RTBC for a check that the doc updates are correct.

Super nit for the sample code, not related to what’s being fixed…

@return array[]

Kinda weird. Probably we want either just:

@return array

Or perhaps something like:

@return string[]

or whatever. Not that we don’t have functions in Drupal that return nested arrays. 😂 but we’re trying to move away from ArrayPI.

@dww, thanks, I did miss that last night.

I changed it to @return string[].