Remove "implementation of" nominalizations from Docblocks

Can'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

Looks good to me, +1

Works for me too. Will be hard to re-learn but not a reason to leave as is.

Does 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.

Patch re-roll

Let's do this ;)

Committed to CVS HEAD. Thanks!

Let's get this documented in the coding standards, please!

Docs updated at http://drupal.org/node/1354

I 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

Sorry, but this was plain wrong.

Implement hook_foo(). sounds like and actually is a command.

Implement does not work as a verb turned into a noun. At least not in this context.

Implementation of hook_foo() 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:

/**
 * Implementation of hook_node_view().
 */

becomes

/**
 * Attach comments to rendered node.
 *
 * @ingroup hook_implementations
 */

Please revert this patch. And do it properly (if at all).

I 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.

Sun (#17 above): Please check out and comment on #487802: Function doc standard for Drupal is non-standard in industry. Would love some support there!

The 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().

Sun: 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...