From eb0c7697c8ba49b417690ac57c97c24f3651c110 Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Sun, 4 Jan 2009 20:04:32 +0000
Subject: - Patch #352712 by dmitrig01: better documentation for
 menu_get_object() and arg().

---
 includes/menu.inc | 20 +++++++++++++-------
 includes/path.inc |  9 +++++----
 2 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/includes/menu.inc b/includes/menu.inc
index 269955429..053230cf8 100644
--- a/includes/menu.inc
+++ b/includes/menu.inc
@@ -727,11 +727,16 @@ function _menu_link_translate(&$item) {
 /**
  * Get a loaded object from a router item.
  *
- * menu_get_object() will provide you the current node on paths like node/5,
- * node/5/revisions/48 etc. menu_get_object('user') will give you the user
- * account on user/5 etc. Note - this function should never be called within a
- * _to_arg function (like user_current_to_arg()) since this may result in an
- * infinite recursion.
+ * menu_get_object() provides access to objects loaded by the current router
+ * item. For example, on the page node/%node, the router loads the %node object,
+ * and calling menu_get_object() will return that. Normally, it is necessary to
+ * specify the type of object referenced, however node is the default.
+ * The following example tests to see whether the node being displayed is of the
+ * "story" content type:
+ * @code
+ * $node = menu_get_object();
+ * $story = $node->type == 'story';
+ * @endcode
  *
  * @param $type
  *   Type of the object. These appear in hook_menu definitions as %type. Core
@@ -739,8 +744,9 @@ function _menu_link_translate(&$item) {
  *   forum_term, menu, menu_link, node, taxonomy_vocabulary, user. See the
  *   relevant {$type}_load function for more on each. Defaults to node.
  * @param $position
- *   The expected position for $type object. For node/%node this is 1, for
- *   comment/reply/%node this is 2. Defaults to 1.
+ *   The position of the object in the path, where the first path segment is 0.
+ *   For node/%node, the position of %node is 1, but for comment/reply/%node,
+ *   it's 2. Defaults to 1.
  * @param $path
  *   See menu_get_item() for more on this. Defaults to the current path.
  */
diff --git a/includes/path.inc b/includes/path.inc
index c48ae8f94..6eedad9bf 100644
--- a/includes/path.inc
+++ b/includes/path.inc
@@ -148,12 +148,13 @@ function drupal_get_normal_path($path, $path_language = '') {
  * Return a component of the current Drupal path.
  *
  * When viewing a page at the path "admin/build/types", for example, arg(0)
- * would return "admin", arg(1) would return "content", and arg(2) would return
- * "types".
+ * returns "admin", arg(1) returns "content", and arg(2) returns "types".
  *
  * Avoid use of this function where possible, as resulting code is hard to read.
- * Instead, attempt to use named arguments in menu callback functions. See the
- * explanation in menu.inc for how to construct callbacks that take arguments.
+ * In menu callback functions, attempt to use named arguments. See the explanation
+ * in menu.inc for how to construct callbacks that take arguments. When attempting
+ * to use this function to load an element from the current path, e.g. loading the
+ * node on a node page, please use menu_get_object() instead.
  *
  * @param $index
  *   The index of the component, where each component is separated by a '/'
-- 
cgit v1.2.3