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
Comment #1
Novitsh CreditAttribution: Novitsh as a volunteer commentedI 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:
Comment #2
Liam MorlandDoing 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.
Comment #3
Liam MorlandComment #4
apadernoIt'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.)Comment #5
apadernoI slightly changed what the documentation page says, just to make more explicit what it is saying.
Comment #6
apadernoAs 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).