Index: modules/menu/menu.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/menu/menu.api.php,v
retrieving revision 1.11
diff -u -r1.11 menu.api.php
--- modules/menu/menu.api.php	30 Sep 2009 13:09:29 -0000	1.11
+++ modules/menu/menu.api.php	30 Sep 2009 20:36:40 -0000
@@ -14,71 +14,113 @@
 /**
  * Define menu items and page callbacks.
  *
- * This hook enables modules to register paths, which determines whose
- * requests are to be handled. Depending on the type of registration
- * requested by each path, a link is placed in the the navigation block and/or
- * an item appears in the menu administration page (q=admin/menu).
+ * This hook enables modules to register paths, in order to define how URL
+ * requests are handled. Depending on the type of registration requested for
+ * each path, besides registering for URL handling, you can also register a link
+ * to be placed in the navigation block and/or an item to be placed in a menu
+ * (usually the Navigation menu). A path and its associated information is
+ * collectively known as a "menu router item".
+ *
+ * For several purposes (see below), your return value can include an array
+ * giving a list of arguments for a callback function. In these arrays, you can
+ * either use literal function arguments (usually strings), or you can use
+ * integers corresponding to path components. If you use integers, when the
+ * callback function is called, the corresponding path components will be
+ * substituted. For instance, when registering for path 'abc/def', integer 0 in
+ * an argument list will be replaced with 'abc', and integer 1 will be replaced
+ * with 'def' when the callback function is called; this can be quite useful to
+ * allow you to reuse a callback function for several different paths. It is
+ * even more useful if your path has wildcards in it. For example, if you
+ * register path 'my_module/%', and someone requests the path 'my_module/foo',
+ * then integer 1 will be replaced with 'foo' when the callback function is
+ * called.
+ *
+ * Your registered paths can also contain special "auto-loader" wildcard
+ * components in the form '%foo', where the % part means that this path
+ * component is a wildcard, and the foo part means that function foo_load() will
+ * be automatically called to load a "foo" object (with the actual path
+ * component value as the input argument to the load function). This object will
+ * be passed into your callback functions in place of the path component during
+ * the substitution step described above. For example, the path
+ * 'node/%node/edit' means that if path 'node/12345/edit' is requested, then
+ * node_load(12345) will automatically be called, and this node object will be
+ * passed to page and access callbacks whose argument list includes the number
+ * 1. You can pass extra arguments into the loader as well; see the "load
+ * arguments" element below.
  *
- * This hook is called rarely - for example when modules are enabled.
+ * This hook is called rarely (for example, when modules are enabled), and
+ * its results are then cached in the database.
  *
  * @return
  *   An array of menu items. Each menu item has a key corresponding to the
- *   Drupal path being registered. The item is an associative array that may
- *   contain the following key-value pairs:
+ *   Drupal path being registered. The corresponding array value is an
+ *   associative array that may contain the following key-value pairs:
  *   - "title": Required. The untranslated title of the menu item.
- *   - "title callback": Function to generate the title, defaults to t().
+ *   - "title callback": Function to generate the title; defaults to t().
  *     If you require only the raw string to be output, set this to FALSE.
- *   - "title arguments": Arguments to send to t() or your custom callback.
+ *   - "title arguments": Arguments to send to t() or your custom callback,
+ *     with path component substitution as described above.
  *   - "description": The untranslated description of the menu item.
  *   - "page callback": The function to call to display a web page when the user
  *     visits the path. If omitted, the parent menu item's callback will be used
  *     instead.
  *   - "page arguments": An array of arguments to pass to the page callback
- *     function. Integer values pass the corresponding URL component (see arg()).
+ *     function, with path component substitution as described above.
  *   - "access callback": A  function returning a boolean value that determines
  *     whether the user has access rights to this menu item. Defaults to
  *     user_access() unless a value is inherited from a parent menu item.
  *   - "access arguments": An array of arguments to pass to the access callback
- *     function. Integer values pass the corresponding URL component.
+ *     function, with path component substitution as described above.
  *   - "theme callback": Optional. A function returning the machine-readable
  *     name of the theme that will be used to render the page. If the function
  *     returns nothing, the main site theme will be used. If no function is
  *     provided, the main site theme will also be used, unless a value is
  *     inherited from a parent menu item.
  *   - "theme arguments": An array of arguments to pass to the theme callback
- *     function. Integer values pass the corresponding URL component.
+ *     function, with path component substitution as described above.
  *   - "file": A file that will be included before the callbacks are accessed;
  *     this allows callback functions to be in separate files. The file should
  *     be relative to the implementing module's directory unless otherwise
- *     specified by the "file path" option.
+ *     specified by the "file path" option. Note: This does not apply to the
+ *     access callback.
  *   - "file path": The path to the folder containing the file specified in
  *     "file". This defaults to the path to the module implementing the hook.
  *   - "load arguments": An array of arguments to be passed to each of the
- *     object loaders in the path. For example, for the router item at
- *     node/%node/revisions/%/view, the array(1, 3) will call node_load() with
- *     the arguments corresponding to the second and fourth URL argument;
- *     as with other arguments, integers are automatically cast to URL
- *     arguments. There are also two "magic" values: "%index" will correspond
- *     to the URL index where the object's load function is specified; "%map"
- *     will correspond to the full menu map, passed in by reference to the
- *     load function.
- *   - "weight": An integer that determines relative position of items in the
- *     menu; higher-weighted items sink. Defaults to 0. When in doubt, leave
+ *     wildcard object loaders in the path. For example, for the path
+ *     node/%node/revisions/%/view, a "load arguments" value of array(1, 3) will
+ *     call node_load() with the second and fourth path components passed in (as
+ *     described above, integers are automatically replaced with path
+ *     components). There are also two "magic" values: "%index" will correspond
+ *     to the index of the wildcard path component, and "%map" will correspond
+ *     to the full menu map, passed in by reference.
+ *   - "weight": An integer that determines the relative position of items in
+ *     the menu; higher-weighted items sink. Defaults to 0. When in doubt, leave
  *     this alone; the default alphabetical order is usually best.
  *   - "menu_name": Optional. Set this to a custom menu if you don't want your
  *     item to be placed in Navigation.
+ *   - "tab_parent": For local task menu items, the path of the task's parent
+ *     item; defaults to the same path without the last component (e.g., the
+ *     default parent for 'admin/people/create' is 'admin/people').
+ *   - "tab_root": For local task menu items, the path of the closest non-tab
+ *     item; same default as "tab_parent".
+ *   - "block callback": Name of a function used to render the block on the
+ *     system administration page for this item (called with no arguments).
+ *     If not provided, system_admin_menu_block() is used to generate it.
+ *   - "position": Position of the block ('left' or 'right') on the system
+ *     administration page for this item.
  *   - "type": A bitmask of flags describing properties of the menu item.
  *     Many shortcut bitmasks are provided as constants in menu.inc:
  *     - MENU_NORMAL_ITEM: Normal menu items show up in the menu tree and can be
  *       moved/hidden by the administrator.
  *     - MENU_CALLBACK: Callbacks simply register a path so that the correct
- *       function is fired when the URL is accessed.
+ *       function is fired when the path is accessed.
  *     - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the
  *       administrator may enable.
  *     - MENU_LOCAL_TASK: Local tasks are rendered as tabs by default.
  *     - MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one
  *       "default" task, that links to the same path as its parent when clicked.
- *     If the "type" key is omitted, MENU_NORMAL_ITEM is assumed.
+ *     If the "type" element is omitted, MENU_NORMAL_ITEM is assumed.
+ *
  * For a detailed usage example, see page_example.module.
  * For comprehensive documentation on the menu system, see
  * http://drupal.org/node/102338.