Should we document AJAX-callback parameters? Considering the PHPCS warning:


  phpcs: Hook implementations should not duplicate @param documentation


Is there any way to tell PHPCS that the function is an AJAX-callback (so that such warnings are generated)?

Or, Should we document all AJAX-callback parameters, with @param PHPDoc?



Background:

There was a discussion in our company about the below AJAX-callback function:

/**
 * Prevents popup's redirection from dashboard to another link.
 *
 * Users were redirected to another page as soon as the Event-creation
 * popup form was submitted, just added an AJAX handler to submit button
 * which prevents the redirect using ajax,
 * and when there is any error on the form, the message is sent to the popup.
 */
function _MYMODULE_popup_submit(array &amp;$form, FormStateInterface $formState) {
  // ...
}


Where one developer insisted on adding @param PHPDoc comments to each AJAX-callback like:

/**
 * Prevents popup's redirection from dashboard to another link.
 *
 * Users were redirected to another page as soon as the Event-creation
 * popup form was submitted, just added an AJAX handler to submit button
 * which prevents the redirection using ajax,
 * and when there is any error on the form, the message is sent to the popup.
 *
 * @param array &amp;$form
 *   All data of the form.
 * @param \Drupal\Core\Form\FormStateInterface $formState
 *   State of the form.
 *
 * @return \Drupal\Core\Ajax\AjaxResponse
 *   Returns the data back as AjaxResponse object.
 */
function _amt_dayview_popup_submit(array &amp;$form, FormStateInterface $formState) {
  // ...
}


And the other considered it as understandable and that it should not be documented:


  ... remember that PHPCS will warn you every time we use @param on any hook, like "phpcs: Hook implementations should not duplicate @param documentation", and just because PHPCS can not differ AJAX-callback from normal functions it does not mean that we should do this ...




Edit: The feature request is created for this on Drupal.org.
Is there any way to tell PHPCS that the function is an AJAX-callback (so that such warnings are generated)?


Yes, it's as simple as implementing hooks except that instead of "Implements hook_", it starts with "Implements callback_".

The only problem is that currently (August 2019) it is not supported by Drupal's PHPCS standard and you don't get any warnings yet. 


  Or, Should we document all AJAX-callback parameters, with @param PHPDoc?


That too is an option, for your newly hired dev interns, but especially when there was no official definition in any existing *.api.php file and when you do not want to write your own *.api.php file.

Source:

In Drupal's Official-documentation of August 2019, we can find below Callback implementation:

/**
 * Implements callback_batch_finished().
 */
function _node_mass_update_batch_finished($success, $results, $operations) {
  // …
}



  Note: Unlike hooks any callback starts with an underscore (i.e. it is "_MYMODULE_descreptive_name").




Callback definition example:

In our case, because Drupal's own *.api.php files did not cover AJAX-callbacks, we added our own *.api.php file to prevent copy/paste until Drupal's own *.api.php files cover that section as well, something like below:

&lt;?php

/**
 * @file
 * Callbacks and hooks related to MYPROJECT system.
 */

/**
 * @addtogroup callbacks
 * @{
 */

use Drupal\Core\Ajax\AjaxResponse;
use Drupal\Core\Ajax\HtmlCommand;
use Drupal\Core\Form\FormStateInterface;

/**
 * Callback for AJAX events.
 *
 * AJAX callback functions can be used to update existing or
 * add new form fields, update values in form fields and more,
 * while users can still interact with the form.
 *
 * @param array &amp;$form
 *   All data of the form.
 * @param \Drupal\Core\Form\FormStateInterface $formState
 *   State of the form.
 *
 * @return \Drupal\Core\Ajax\AjaxResponse
 *   Returns the data back as AjaxResponse object.
 */
function callback_form_ajax(array &amp;$form, FormStateInterface $formState) {
  // Here we do something meaningful with the results.
  $response = new AjaxResponse();
  $response-&gt;addCommand(new HtmlCommand('#message-box', 'my message.'));
  return $response;
}

/**
 * @} End of "addtogroup callbacks".
 */

/**
 * @addtogroup hooks
 * @{
 */

/* Place any hook definitions here. */

/**
 * @} End of "addtogroup hooks"
 */



Callback implementation example:

/**
 * Implements callback_form_ajax().
 *
 * Prevents popup's redirection from dashboard to another link.
 *
 * Users were redirected to another page as soon as the Event-creation
 * popup form was submitted, just added an AJAX handler to submit button.
 * which prevents the redirect using ajax,
 * and when there is any error on the form, the message is sent to the popup.
 */
function _amt_dayview_popup_submit(array &amp;$form, FormStateInterface $formState) {
  // ...
}