Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
This one style issue has always driven me crazy, so here is a patch, finally, to remove it.
In English usage, a nominalization is a verb turned into a noun. Generally is obscures clarity and should be avoided.
All throughout core, we have:
/**
* Implementation of hook_foo().
*/
The docblock standard is a short, active sentence. Such as "Retrieve a blocked IP address from the database." (Taken from blocked_ip_load()).
This patch changes _all_ instances of "Implementation of hook_foo()" to "Implement hook_foo()" in one pass.
Comment | File | Size | Author |
---|---|---|---|
#9 | implement_no_of.patch | 169.85 KB | stella |
implement_no_of.patch | 167.95 KB | agentrickard | |
Comments
Comment #1
agentrickardTag.
Comment #2
EclipseGc CreditAttribution: EclipseGc commentedCan't say this bothers me one way or another, but the patch looks good, and I appreciate anyone trying to make our coding standards better.
Eclipse
Comment #3
stella CreditAttribution: stella commentedLooks good to me, +1
Comment #4
catchWorks for me too. Will be hard to re-learn but not a reason to leave as is.
Comment #5
Crell CreditAttribution: Crell commentedDoes this actually match the recommended verb structure for the rest of are docblocks? There are some verbage standards that require a noun phrase and others that require a verb phrase. I don't actually know what our standard is, if any.
Comment #6
agentrickardYes.
http://drupal.org/node/1354 -- Documenting Functions.
The standard for documenting hook implementations (right below) contradicts this verb rule.
Comment #7
stella CreditAttribution: stella commentedComment #9
stella CreditAttribution: stella commentedPatch re-roll
Comment #10
Damien Tournoud CreditAttribution: Damien Tournoud commentedLet's do this ;)
Comment #11
Dries CreditAttribution: Dries commentedCommitted to CVS HEAD. Thanks!
Comment #12
webchickLet's get this documented in the coding standards, please!
Comment #13
stella CreditAttribution: stella commentedDocs updated at http://drupal.org/node/1354
Comment #14
stella CreditAttribution: stella commentedComment #15
jhodgdonI think the standard mentioned in #6 is wrong, and filed a separate issue on this -- see #487802: Function doc standard for Drupal is non-standard in industry
Comment #16
agentrickardAgreed. But this patch is still better than before. So this stays 'fixed.'
Comment #17
sunSorry, but this was plain wrong.
sounds like and actually is a command.
does not work as a verb turned into a noun. At least not in this context.
is an exception to our documentation standards, because it does not document or summarize the function. It is rather a human-readable equivalent of@ingroup hook_implementations
.If we want to remove this exception and adhere to the current documentation standards, the proper change is to appropriately convert all those summaries into summaries that document the actual function body.
That would mean:
becomes
Please revert this patch. And do it properly (if at all).
Comment #18
agentrickardNo.
Comment #19
catchI don't think we can do meaningful one line summaries for a lot of hooks - menu block_$op form_alter etc. Not to mention that'd break grepping for hook implementations.
Comment #20
agentrickardMy point is that rolling this back doesn't improve anything. If you want one-line summaries, that is a separate issue.
Comment #21
jhodgdonSun (#17 above): Please check out and comment on #487802: Function doc standard for Drupal is non-standard in industry. Would love some support there!
Comment #22
sunThe point is that rolling this back reverts to something that makes sense when reading it.
"Implement hook_foo()." sounds like a todo. A reminder to implement hook_foo().
Comment #23
jhodgdonSun: I totally agree with you. If we can get agreement on #487802: Function doc standard for Drupal is non-standard in industry, then my plan is at least to change them to "implements", and fix the other 2nd-person doc headers (they are all over the code). At the moment, however, our doc style guidelines say that 2nd person is the standard. It is not a good standard, in my opinion, but "Implement hook_foo()" is in compliance with the standard. Hence issue 487802. Please comment there...
Comment #24
Crell CreditAttribution: Crell commentedComment #25
sunComment #26
Crell CreditAttribution: Crell commented