6

Can a function like _menu_block_block_configure() be documented as Implements hook_block_configure()?

It initially threw me off to see an internal function (with underscore prefix) documented as a hook implementation, but if the actual work is being done here, then there is some sense to it.

Is this the proper way to document it?

Improve this question

1 Answer 1

Reset to default
4

TL;DR: Yes, it's fine and widespread too!

It might look kind of unorthodox, but it's just offloading the bulk of the hook implementation to an include to keep the main .module file smaller.

A lot of other contributed modules do this too, for example the Display Suite module, the Views module, and a bunch of others too.

Improve this answer
3
  • Thanks, Alex. I do know why one would offload in this way; it was a documentation question. Anyhoo, that's what I figured. And, by the way, I'm certainly not in the habit of second guessing established maintainers like Dave Reid (in the case of Menu Block); I just wanted to confirm that this is the norm before I follow suit. Thanks again and cheers -
    – othermachines
    Commented Aug 14, 2015 at 18:53
  • 2
    I don't know if this is should be considered an established norm, or rather a matter of taste. At least I don't think it is documented that this is the "correct" behavior. Personally, I would prefer to label the actual hook implementation with "Implements hook_*()", but choose a somewhat distinct wording for the helper function. E.g. "Called by hook_*()". But I guess why not just do what others do..
    – donquixote
    Commented Aug 14, 2015 at 19:43
  • 1
    @donquixote - "If a million people do a stupid thing, it's still a stupid thing." :) Thanks for your input. I agree that it isn't necessarily a good way, and would prefer something more accurately descriptive. Why not describe what you are actually doing, after all? But it also makes some sense that these undocumented "norms" - what most people do - would be considered the most acceptable alternative to a written standard because, well, popular usage is often how standards become standards in the first place.
    – othermachines
    Commented Aug 14, 2015 at 22:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.