Issue #1182970 by mr.baileys: Improvements to hook_menu() documentation.

modules/system/system.api.php

@@ -964,9 +964,12 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) {
  * When path 'abc/def' is requested, the page callback function will get 'def'
  * as the first argument and (always) 'foo' as the second argument.
  *
- * 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 optional path arguments as described above.
+ * If a page callback function uses an argument list array, and its path is
+ * requested with optional path arguments, then the list array's arguments are
+ * passed to the callback function first, followed by the optional path
+ * arguments. Using the above example, when path 'abc/def/bar/baz' is requested,
+ * mymodule_abc_view() will be called with 'def', 'foo', 'bar' and 'baz' as
+ * arguments, in that order.
  *
  * Special care should be taken for the page callback drupal_get_form(), because
  * your specific form callback function will always receive $form and