No documentation standard for hook_update_N() summaries [policy, no patch]

If these do go to the UI, it would really be even better if the API was changed so that the strings were translatable, rather than being parsed out of the API documentation. Of course that would be d8 and beyond only, but we can't go back and impose new docs standards on d7 and previous anyway.

But anyway I don't see that happening in:
http://api.drupal.org/api/drupal/update.php/function/update_results_page/7
If it's just drush, then I'm not too worried about it.

So I'm not all that familiar with the update code... can you point me in the right direction, where the doc header is parsed and this is displayed in the update UI, if I missed it?

Ah, I see! Thanks for the clarification and code pointer.

OK then, agreed, we should definitely make a standard. Proposal [to go into the hook implementations section http://drupal.org/node/1354#hookimpl , or right after that with a link to this special case]:

-----------
For hook_update_N() implementations, there is a different standard, because the documentation's first line is displayed in the results section when update.php is run. So they are documented as follows:

/**
 * Add several fields to the {node_revision} table.
 *
 * Longer description can go here, if necessary.
 */
 module_name_update_7002() {
 }

---------------

HOWEVER, I still think that if these doc strings are displayed in the UI then they should be translatable. Grabbing the one-line API documentation is not a good idea, really. I mean, would your average Drupal administrator who might not speak English find any of those English descriptions at all useful? But I guess that is a separate issue maybe...

Just filed:
#1417072: Update descriptions are not internationalized/translatable

Wow, that doc page has no function header docs at all, eek! So we should add the header docs there too as a model, once agreed upon.

If we are not going to be translating the description text, then the summary makes sense, and is what I thought we were already doing. :-) (One line summary of what the function does, longer description if needed.)

If we are going to be translating description text, I am going to put on a flame-retardant vest and suggest that update functions turn into update classes that implement a given interface; that interface includes title() and description() methods (or something), which return translated text, as well as an execute() method that is, roughly, the body of the function we have now.

Again, if no translation is necessary then I don't think objects are necessary here at this time.

+1 on making this translatable in D8. And certainly +1 on documenting this in the standards (and the doc for hook_update_N()!) for D7.

Also, while I am definitely not a fan of objectifying things for objectification's sake (though I don't have a flame-thrower dedicated for the purpose), this seems like an obvious place to use classes, as here, clearly, things should be grouped together functionality-wise in an obvious way. All alternatives that come to mind smell badly (having a distinct hook_update_N_description()? *shudder* Having a hook_update_descriptions() that returns a map from update numbers to descriptions? *eww*).

Of course, with the change to PSR, this would mean a lot fo tinsy class files, but then again, these functions/classes really should only be loaded when needed, which one-class-per-file helps us do. So overall +1 to move to update classes.

And in any case, this pattern (which has surprised/bitten me in the past when I implemented my first hook_update_N()'s) is certainly an odd thing---I don't think there is any other place in core where doc headers are parsed and displayed to the user (I may be wrong).

Hm. Thought I already commented on this, but maybe it was a different issue...

Please confirm with some actual translators that it's desirable to make these strings translatable. I doubt that it is. We actually removed translatability from database schema description strings because translators noted that a) the strings were highly technical, and thus difficult for people to translate, and b) they were only viewable by basically one person per Drupal site which made translating them a waste of time.

Yes, there is already another issue for translatable (see comment #5 above).

Right, stating the obvious.

Seems fine. That's effectively our de-facto standard anyway.

Given that everyone agrees this is a de facto standard, I went ahead and added it to:
http://drupal.org/node/1354#hookimpl

I also edited the examples on
http://drupal.org/node/150215
and made sure they all had one-line summaries as models.

I'd say this is fixed.

Ok, so now is it not "required" to use 3rd person verbs, or is it not advised or is it forbidden (in update function first line phpdoc)? This is not really clear from the docs :/

That is a good question actually, and I guess we should discuss it.

We use 3rd person verbs for function docs because we're saying "[This function] Does some action.".

The purpose of these one-line descriptions though is not only to say what the function does for purposes of api.drupal.org, but also to say what is going to happen when someone runs update.php. As in, "[If you run this update, it will] Add something to your xyz table.".

So... yeah, we should adopt one or the other, and make it clear in the docs... Any thoughts on which?

Ah, let's see. What do we have in core? In drupal 8:

system.install:
Enable entity module.
Move from the Garland theme.

node.install
Rename node type language variable names.

etc. So it seems like our de-facto standard is what is in the docs now. Any thoughts?

Imperative makes more sense when it's shown to the user. They have no context other than "there's this string on the page that says what the code just did". Imperative makes sense there; "Enables" is just confusing.

OK, I think (a) existing core docs and (b) several people just now and (c) past reviewers of the standard are all in agreement with the standard staying as it is documented now. I will add a note about using the imperative form of the verb to 1354.