I am reporting https://www.drupal.org/docs/develop/coding-standards/api-documentation-a... to moderators because I have noticed that in many .install files, right above the first update hook there is the following comment.

/**
 * Implements hook_update_N().
 */

It makes sense to me that this be there and fits with the standard of having an "Implements..." line for each hook implementation. In a project I am working on, someone removed it saying it was unneeded. So, should the "Implements hook_update_N()" comment be there or not? I think the documentation should either explicitly say that it should appear or that the general standard of having an "Implements..." line does not apply to updates.

Comments

Novitsh’s picture

I think it's good to keep all docblocks the same. I know that Drush for example reads the block and displays it in the updb command.
Maybe Drush should get an update and read the second or third line instead of the first?

Example:

/**
 * Implements hook_update_N().
 * 
 * Set the variable to new value.
 */
function hook_update_7001() {
  variable_set();
}
Liam Morland’s picture

Issue summary: View changes

Doing it as suggested in #1 means repeating "Implements hook_update_N()" with every implementation, which I think is unnecessary. It would also require re-writing every module to look at the second line.

Liam Morland’s picture

Issue summary: View changes
apaderno’s picture

Title: Moderation report for API documentation and comment standards » Make the coding standards clearer about the comment for a hook_update_N() implementation
Status: Active » Fixed

It's not just Drush to read the comment before an update hook. Also the user interface showing the pending updates uses that comment as description for the update.

The coding standards already make clear the documentation comment for hook_update_N() doesn't follow the same format used for other hooks. (Emphasis is mine.)

These use a different syntax, because the documentation summary (first line) is displayed to someone running update.php to tell them which updates need to run.

apaderno’s picture

Issue summary: View changes

I slightly changed what the documentation page says, just to make more explicit what it is saying.

These hooks use a different syntax because the documentation summary (the first line) is displayed to users running update.php to tell them which updates need to run. So they are documented like in the following comment.

apaderno’s picture

As side note, any change to the coding standards are discussed on a specific project (https://www.drupal.org/project/coding_standards). If you think the comment for hook_update_N() should always include the Implements part, you should propose it on that issue queue (if it was not proposed before).

Status: Fixed » Closed (fixed)

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