hook_menu API docs missing some elements

The doc is also malformed (Return Value header is at the bottom of the page, after the text explaining what the form elements are, due to extra newline). I will patch both issues at once

Here's a patch.

applied against head and the documentation changes were made. Looks good

Committed to CVS HEAD.

+ *   - "file": A file that will be included before the callbacks are accessed.
+ *     this allows callback functions to be in separate files. The file should

Either use a comma, or start the next sentence with an uppercase letter.

+ *     the arguments corresponding to the second and fourth url argument;
+ *     as with other arguments, integers are automatically cast to url
...
+ *     to the url index where the object's load function is specified; "%map"

"URL" is always uppercase.

Oops, nice catch, sun. The attached patch fixes the grammatical problems pointed out in #13, and also removes an extraneous period I noticed from the hook_menu() docs.

This looks like an excellent grammar, punctuation, and capitalization update to me.

However, the original patch (which was applied) and this patch as well didn't fix one of the problems in http://api.drupal.org/api/function/hook_menu/7, as noted in comment #1 above -- which is that there is a big section of bullet points that belongs in the Return Value section, but because of an extra newline, that section is not being picked up as part of the Return Value section (it's up in the main documentation). So, it would be good to add that to your patch.

Also, note that a port to 6.x is also needed, which would incorporate the changes from #4 and this current patch.

As far as I understand, the tab_ stuff does internal tab-related stuff that's best not to mess with. I can add documentation ("this is used internally") for those if you'd like. As far as I understand again, block callback refers to the callback that returns the block on the administration page ("Content management" / "Site building" / etc.)

I believe the attached patch should fix the problem with blank lines.

Committed to CVS HEAD. I'm setting this to 'code needs work' so we can add the missing bits.

Actually the 'file' and 'file path' elements have been removed from hook_menu() in Drupal 7 (http://drupal.org/node/224333#menu_file_path)

I'll patch this...

I looked through the code, including system_install(), _menu_router_build(), and other functions that deal with the menu system.

There were several components missing, and several that had to be removed.

I also did some grammatical/style/clarity edits, since I can never resist those :), fixed an over-80-character line, and added a section to the hook_menu() doc that explains the magic auto-loading functionality (which I was amazed at when I discovered it once by delving into the code, and think should be there in the doc, because it is certainly not obvious until you find out about it).

Anyway, here's a patch of revisions to the hook_menu() documentation.

Maybe we don't even need a link to arg() there at all? I just reformatted what was there into 80-character line, but thinking more about it, I don't really see what a link to the arg() function does for the explanation. In any case, any time you put a function name in like arg() with the parens, the API display module turns it into a magic link.

Regarding your second comment, this is not the same as a load argument actually. Load arguments refers to making the load_foo() function take extra arguments. This refers to making $node substitute for 12345 if your page or access function asks for path component #2. But I agree maybe the current wording could be confusing... Not sure what the best wording is... any ideas?

Wait, I have an idea. New patch coming...

Here it is...

This time, I decided a paragraph at the top explaining the path component substitution also made sense.

I corrected a couple of repetitions.
+ * can also register a link to be placed in the the navigation block

+ * Your registered paths can contain also contain special

Also, throughout the text, I see several uses of "pass into", "pass to" and such, related to the act of sending data to functions/callbacks. As a non-native English speaker, my bet would be on "pass on to" as the correct form, but I leave this matter to natives.

Oh, testing bot...

That above patch indeed would not apply, due to other changes...

Here is a new patch.

I'm assuming that the file/file path stuff needs to be there again, since the registry went away? At least, I see it in node_menu(), so I am assuming it should be left in the hook_menu() doc now.

Revamped. Code examples usually do better.

Also, what's this "again"? Awkward wording... I think maybe you are trying to say it is a nested array?

+ * hook_menu() implementations return an associative array that contains again
+ * an associative array for each path. The definition for each path may refer to

Anyway, I think the prose in your version needs some work... it's probably no surprise that I liked my prose explanations better. :)

[deleted]

Just a note: #583398: Not clear that access callbacks have to be in the same file as hook_menu.

Both my patch in #34 and sun's patch in #35 address this (making sure the file element says it doesn't apply to access callbacks). Any future versions should too.

Thanks for the reviews + suggestions!

Incorporated those.

Furthermore, I realized that we explain all that advanced argument handling stuff, but not a single word about the most trivial case: optional default arguments. Revised nightmare attached.

This is great.

Tagging.

Committed to CVS HEAD. Thanks!

Should we consider porting all/some of this patch to Drupal 6? I think it would be a good idea to have this explanation of auto-load and arg substitution there as well.

Check to make sure, but I think "theme callback" and args were added in D7. Maybe other components? "block callback"? "tab root"?

Also might be good to wait a day or two and incorporate
#536788: Provide documentation on making menu tabs
into the same D6 port, assuming it gets accepted/committed.

After a careful look through the D6 code, I believe that only these two items need to be omitted for D6:
theme callback
theme arguments

That other issue #536788: Provide documentation on making menu tabs was committed to D7. So they can be ported to D6 together, if desired.

Actually, I would wait on porting after all -- there is more discussion happening on that other issue... more changes to hook_menu doc happening... I am going to suggest that this patch NOT be ported, and we do the porting on the other issue instead.