In the contact.module there are the following documentation comments.

/**
 * Implements hook_form_FORM_ID_alter().
 *
 * Add the enable personal contact form to an individual user's account page.
 *
 * @see \Drupal\user\ProfileForm::form()
 */
/**
 * Implements hook_form_FORM_ID_alter().
 *
 * Add the default personal contact setting on the user settings page.
 *
 * @see \Drupal\user\AccountSettingsForm
 */
/**
 * Form submission handler for user_admin_settings().
 *
 * @see contact_form_user_admin_settings_alter()
 */
function contact_form_user_admin_settings_submit($form, FormStateInterface $form_state) {
  \Drupal::configFactory()->getEditable('contact.settings')
    ->set('user_default_enabled', $form_state->getValue('contact_default_status'))
    ->save();
}

The description should say for which form the hook implementation or the form submission handler is, as the examples on Drupal API documentation standards for functions / Form-generating functions and Drupal API documentation standards for functions / Hook implementation show. Since form builders are now classes, the description cannot reference a function, which is no longer exist in Drupal 8+.

Issue fork drupal-3461741

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

apaderno created an issue. See original summary.

avpaderno’s picture

Issue summary: View changes
sourav_paul’s picture

Assigned: Unassigned » sourav_paul

sourav_paul’s picture

Assigned: sourav_paul » Unassigned
Status: Active » Needs review
avpaderno’s picture

Status: Needs review » Needs work

The line that has been changed is already correct. What needs to be changed is Form submission handler for user_admin_settings().

avpaderno’s picture

Title: The short description references a form builder function that is no longer implemented » Description for hook_form_FORM_ID_alter() and form submission handlers must say for which form the hook or the form submission handler is
Issue summary: View changes
Status: Needs work » Active

Also, there are more comments which needs to be changed, in that file. Let's expand the issue to those comments too.

sourav_paul’s picture

Status: Active » Needs review
smustgrave’s picture

Status: Needs review » Reviewed & tested by the community

Going to mark it as this does help. Only one I was iffy about is

Saves the contact page setting.

seems like it's not needed since it's a form submission handler.

avpaderno’s picture

@smustgrave Saves the contact page setting. could be removed. I left it because the short description already used it, but it is not necessary, given the code used from that hook.

quietone’s picture

Title: Description for hook_form_FORM_ID_alter() and form submission handlers must say for which form the hook or the form submission handler is » Add form class to summary for hooks and form submission handler in contact.module

The description must say for which form the hook implementation or the form submission handler is.

I can not find a coding standard that support this statement. If someone can point that out, add a link here.

avpaderno’s picture

Issue summary: View changes
avpaderno’s picture

Issue summary: View changes
avpaderno’s picture

Issue summary: View changes
quietone’s picture

Assigned: Unassigned » quietone

@apaderno, thanks for taking the time to update the issue summary directing readers to the standards.

This is certainly an improvement. It does raise the question of if updating these docs for these functions should be done throughout core so we are sure everything is updated.

I intend to commit this within 24 hours.

  • quietone committed 98e24c88 on 11.0.x
    Issue #3461741 by Sourav_Paul, avpaderno, smustgrave: Add form class to...

  • quietone committed 440d09be on 11.x
    Issue #3461741 by Sourav_Paul, avpaderno, smustgrave: Add form class to...
quietone’s picture

Status: Reviewed & tested by the community » Fixed

Committed to 11.x and 11.0.x Thanks for the improvement!

quietone’s picture

Version: 11.x-dev » 11.0.x-dev
quietone’s picture

Assigned: quietone » Unassigned

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.