As a new developer, I remember one of the things that took me a bit to grasp regarding the hook system was actually how to plug into the hook system. I think we should have some common help text saying "Replace hook_ with yourmodulename_" or just literally change hook_ in the code example so it's really intuitive: "If I want my module to do this, I take the name from MYMODULENAME.module and replace hook with that."

Anyone agree? I think this would lower the barrier of entry. If there's some positive feedback I'll do this.

Comments

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

If we do this, let's please use EXAMPLE, rather than YOURMODULENAME.

I do remember being confused by this myself. Now the only thing I worry about is if new people will still know what a "hook" is if such a change is made. They'd still be identified as such in the PHPDoc, I suppose.

RobRoy’s picture

RobRoy commented

It will still be called a hook everywhere else. Just change it in the example code.

I want to clearly convey that you put yourmodulename there and example is still to ambiguous. How about example_module_foo in italics then?

Dixen’s picture

Dixen commented

I would have to most certainly agree with this change, perhaps even across the entire documentation really. I am new to developing in Drupal and it's these little things that trip me up constantly. In fact, just tonight I was in #drupal with an issue where I had named the block function for my module "example_info_block"... obviously the "_info" made it impossible to get this working.

+2 for this one

emmajane’s picture

emmajane commented
Status: Active » Closed (won't fix)

If the documentation is changed in core, API won't properly index the code. I'm marking this as "won't fix." Please re-open with more information on how this would actually work with our existing system.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Closed (won't fix) » Active

What emmajane is saying is that pages like http://api.drupal.org/api/function/hook_block/6 are indexed on api.drupal.org by the function name for the example code. That page needs to be indexed as hook_block(), or no one will be able to locate it. So we cannot change the name of the sample code to have a function name of YOURMODULENAMEHERE_block() or EXAMPLE_block() or whatever. Sorry!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Closed (won't fix)

Did not mean to change the status, sorry.