menu_link_save() needs more detail [#1126370]

API documentation does not indicate 2 important steps when calling menu_link_save() in a custom module:

Users should normalize the link_path key using drupal_get_normal_path before passing it into menu_link_save()
Also, in order for the newly saved link to work, will need to clear the menu cache by calling menu_cache_clear_all() afterward

More details can be found at: http://api.drupal.org/api/drupal/includes--menu.inc/function/menu_link_s...

Comment	File	Size	Author
#3	1126370-Changed-menu_link_save-docs.patch	2.17 KB	jn2
#1	1126370.patch	756 bytes	kim-day

Comments

Status	File	Size
new	1126370.patch	756 bytes

Comment #2

jhodgdon

she/her

English

commented 14 April 2011 at 22:06

Title:	Documentation problem with menu_link_save()	» menu_link_save() needs more detail
Version:	7.x-dev	» 8.x-dev
Status:	Needs review	» Needs work

This doc addition seems like a reasonable idea.

The patch needs a small amount of work:
a) There are spaces at the ends of a few lines - those need to be removed.
b) I'm not sure what "custom code" is as opposed to other types of code? I think you could just say "After calling this function, rebuild...".
c) It would be nice to bring this documentation up to standards while you're in here, by also fixing the first line: Save -> Saves.
d) And maybe it would also be nice to fix up the @param section to something like this:

An associative array representing a menu link item, with elements:
- link_path: (required) The path of the menu item, which should be normalized ...
- link_title: (required) The title of the menu item.
- menu_name: (optional) The machine name of the menu to put the link in (defaults to 'navigation').
(etc.)

See http://drupal.org/node/1354#lists and http://drupal.org/node/1354#functions for (d) and (c) respectively.

Thanks!