Index: modules/menu/menu.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/menu/menu.api.php,v
retrieving revision 1.14
diff -u -r1.14 menu.api.php
--- modules/menu/menu.api.php	5 Oct 2009 04:36:39 -0000	1.14
+++ modules/menu/menu.api.php	5 Oct 2009 17:55:59 -0000
@@ -15,17 +15,19 @@
  * Define menu items and page callbacks.
  *
  * This hook enables modules to register paths in order to define how URL
- * requests are handled. Paths may be registered for URL handling only, but can
- * also register a link to be placed in a menu (usually the Navigation menu). A
+ * requests are handled. Paths may be registered for URL handling only, or they
+ * can register a link to be placed in a menu (usually the Navigation menu). A
  * path and its associated information is commonly called a "menu router item".
  *
  * hook_menu() implementations return an associative array whose keys define
- * paths and whose values are an associative array defining properties for each
- * path. The definition for each path may refer to a callback function that is
- * invoked when the registered path is requested. In case there is no other
- * registered path that fits the requested path better, any further path
- * components are optionally passed to the callback function by default.
- * For example, when registering the path 'abc/def':
+ * paths and whose values are associative arrays of properties for each path.
+ * (The complete list of properties is in the return value section below.)
+ *
+ * The definition for each path may include a page callback function, which is
+ * invoked when the registered path is requested. If there is no other
+ * registered path that fits the requested path better, any additional path
+ * components are passed to the page callback function. For example, your module
+ * could register the path 'abc/def':
  * @code
  *   function mymodule_menu() {
  *     $items['abc/def'] = array(
@@ -37,17 +39,18 @@
  *     // ...
  *   }
  * @endcode
- * When the path 'abc/def' was requested, then no further arguments would be
- * passed to the callback function, so $ghi and $jkl would take the default
- * values as defined in the function signature.
- * In case 'abc/def/123/foo' was requested, then $ghi would be '123' and $jkl
- * would be 'foo'.
- *
- * In addition to optional path arguments, the definition for each path may
- * specify a list of arguments for each callback function as an array. These
- * argument lists may contain fixed/hard-coded argument values, but may also
- * contain integers that correspond to path components. When integers are used
- * and the callback function is called, the corresponding path components will
+ * When path 'abc/def' is requested, no further path components are in the
+ * request, and no additional arguments are passed to the callback function
+ * (so $ghi and $jkl will take the default values from the function signature).
+ * When 'abc/def/123/foo' is requested, $ghi will be '123' and $jkl will be
+ * 'foo'. Note that this automatic passing of additional path arguments applies
+ * only to page and theme callback functions.
+ *
+ * In addition to the arguments from optional path components, the page callback
+ * and other callback functions may specify argument lists as arrays. These
+ * argument lists may contain fixed/hard-coded argument values, as well as
+ * integers that correspond to path components. When integers are used and the
+ * callback function is called, the corresponding path components will
  * be substituted. For example:
  * @code
  *   function mymodule_menu() {
@@ -57,57 +60,55 @@
  *     );
  *   }
  * @endcode
- * When the path 'abc/def' was requested, the callback function would get 'def'
- * as first argument and (always) 'foo' as second argument.
- * The integer 1 in an argument list would be replaced with 'def' and integer 0
- * would be replaced with 'abc', i.e. path components are counted from zero.
- * This allows to re-use a callback function for several different paths.
+ * When path 'abc/def' is requested, the callback function would get 'def'
+ * as the first argument and (always) 'foo' as second argument. That is,
+ * the integer 0 in an argument list would be replaced with 'abc' and integer 1
+ * would be replaced with 'def' (path components are numbered starting from
+ * zero). This substitution feature allows you to re-use a callback function for
+ * several different paths.
  *
  * Arguments may also be used to replace wildcards within paths. For example,
- * when registering the path 'my-module/%/edit':
+ * your module could register path 'my-module/%/edit':
  * @code
  *   $items['my-module/%/edit'] = array(
  *     'page callback' => 'mymodule_abc_edit',
  *     'page arguments' => array(1),
  *   );
  * @endcode
- * When the path 'my-module/foo/edit' is requested, then integer 1 will be
- * replaced with 'foo' and passed to the callback function.
+ * When path 'my-module/foo/edit' is requested, integer 1 will be replaced with
+ * 'foo' and passed to the callback function.
  *
  * Registered paths may also contain special "auto-loader" wildcard components
  * in the form of '%mymodule_abc', where the '%' part means that this path
  * component is a wildcard, and the 'mymodule_abc' part defines the prefix for a
  * menu argument loader function, which here would be mymodule_abc_load().
- * For example, when registering the path 'my-module/%mymodule_abc/edit':
+ * For example, your module could register path 'my-module/%mymodule_abc/edit':
  * @code
  *   $items['my-module/%mymodule_abc/edit'] = array(
  *     'page callback' => 'mymodule_abc_edit',
  *     'page arguments' => array(1),
  *   );
  * @endcode
- * When the path 'my-module/123/edit' is requested, then the argument loader
- * function mymodule_abc_load() will be invoked with the argument '123', and it
- * is supposed to take that value to load and return data for "abc" having the
- * internal id 123:
+ * When path 'my-module/123/edit' is requested, the argument loader function
+ * mymodule_abc_load() will be invoked with the argument '123'. This function
+ * should load and return an "abc" object with internal id '123':
  * @code
  *   function mymodule_abc_load($abc_id) {
  *     return db_query("SELECT * FROM {mymodule_abc} WHERE abc_id = :abc_id", array(':abc_id' => $abc_id))->fetchObject();
  *   }
  * @endcode
- * The returned data of the argument loader will be passed in place of the
- * original path component to all callback functions referring to that (integer)
- * component in their argument list.
- * Menu argument loader functions may also be passed additional arguments; see
- * "load arguments" below.
- *
- * If a registered path defines an argument list, then those defined arguments
- * will always be passed first to the callback function. In case there are any
- * further components contained in the requested path, then those will always
- * come last.
+ * The returned object from the argument loader function will be passed in place
+ * of the original path component to all callback functions referring to that
+ * (integer) component in their argument list. Argument loader functions may
+ * also be passed additional arguments; see "load arguments" below.
+ *
+ * Note that if a page or theme callback function has an argument list array,
+ * these arguments will be passed first to the function, followed by any
+ * any arguments generated by additional path arguments as described above.
  *
  * Special care should be taken for the page callback drupal_get_form(), because
- * the callback function will always receive $form and &$form_state as the very
- * first function arguments:
+ * the callback function will always receive $form and &$form_state as the first
+ * function arguments:
  * @code
  *   function mymodule_abc_form($form, &$form_state) {
  *     // ...
@@ -116,7 +117,6 @@
  * @endcode
  * See @link form_api Form API documentation @endlink for details.
  *
- *
  * You can also make groups of menu items to be rendered (by default) as tabs
  * on a page. To do that, first create one menu item of type MENU_NORMAL_ITEM,
  * with your chosen path, such as 'foo'. Then duplicate that menu item, using a
@@ -135,7 +135,8 @@
  * $items['admin/config/foo/global'] = array(
  *   'title' => 'Global settings',
  *   'type' => MENU_DEFAULT_LOCAL_TASK,
- *   // page callback, etc. need to be added here
+ *   // access callback, page callback, and theme callback will be inherited
+ *   // from 'admin/config/foo', if not specified here to override
  * );
  * // Make an additional tab called "Node settings"
  * $items['admin/config/foo/node'] = array(
@@ -175,11 +176,11 @@
  *     inherited from a parent menu item.
  *   - "theme arguments": An array of arguments to pass to the theme callback
  *     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. Note: This does not apply to the
- *     'access callback'.
+ *   - "file": A file that will be included before the page callback is called;
+ *     this allows page 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. Does not apply to other
+ *     callbacks (only page 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
@@ -215,7 +216,7 @@
  *       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.
+ *       "default" task, which should display the same page as the parent item.
  *     If the "type" element is omitted, MENU_NORMAL_ITEM is assumed.
  *
  * For a detailed usage example, see page_example.module.