There was a small mistake in the documentation for the first hook_menu example: it mentions the menu item 'menu_example/simplest', which should be 'menu_example'.

Patch attached. I also took the liberty to expand the explanation a bit.

CommentFileSizeAuthor
#10 hook_menu_documentation-1097438-4.patch2.67 KBtr
#4 hook_menu_documentation-1097438-4.patch2.94 KBpfrenssen
menu_example_docupdate.patch804 bytespfrenssen

Comments

Anonymous’s picture

Anonymous (not verified) commented
Title: Improvement of hook_menu documentation » Improvement of hook_menu documentation, coding standards
Category: feature » task

Thanks for pointing this out, your documentation is a big improvement. We may still want to make more changes to this example, though.

The simplest kind of menu: A simple call to a function with a menu entry.

Using the words 'menu entry' might be confusing here. Calling the routing system the Menu system is a bit of a misnomer. If someone doesn't yet understand the function of the menu router, they will probably assume that this is about placing a link in the menu.

Also, there are other problems with the example as it currently is, like the fact that parts of the array are commented out. Ben Melancon and Stella have verified that it is against coding standard to commit code that is commented out. Anything that is being hashed out and is commented for that reason should actually be in patches. While many people still do commit code that is commented out, I don't think that we should demonstrate that in examples.

rfay’s picture

rfay
he,him
Primary language English
Location Palisade, CO, USA
commented

I'm in favor of allowing commented-out sections in Examples. It's a teaching module, so should get some leniency. The option is putting docblocks with @code sections, which is almost exactly the same thing, but distracts from the point. When you're looking at the code, it's good to see some alternatives.

Commented-out code is just comments and can be very useful.

I'm sure the coding standard is about the situation where somebody comments out a useless block instead of deleting it. That's a bad thing, as it's distracting. However, if we use commented out code to demonstrate alternatives or make a point, that's not bad.

ilo’s picture

ilo commented

Edited: oh, I thought I was writting in the contextual menu entries issue, sorry.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
StatusFileSize
new hook_menu_documentation-1097438-4.patch2.94 KB

New patch which expands the documentation a bit more and clarifies the 'menu entry' confusion.

I agree with rfay that using commented out code should be acceptable for instructional purposes. It is different when someone is committing commented out blocks of obsolete or temporary code.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Status: Active » Needs review

Changing status.

dave reid’s picture

dave reid
he/him
Primary language English
Location Nebraska USA
commented
Version: » 7.x-1.x-dev
tr’s picture

tr commented

I re-rolled this to work with the current -dev.

tr’s picture

tr commented

I re-rolled this to work with the current -dev.

Status: Needs review » Needs work

The last submitted patch, hook_menu_documentation-1097438-4.patch, failed testing.

tr’s picture

tr commented
Status: Needs work » Needs review
StatusFileSize
new hook_menu_documentation-1097438-4.patch2.67 KB

Hmm, double post, and patch didn't get attached properly - bad URL instead. How did that happen? Let's try again.

rfay’s picture

rfay
he,him
Primary language English
Location Palisade, CO, USA
commented
Status: Needs review » Fixed

Thanks so much!

Committed:
D7: 6ad2e27
D8: 718c44c

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.