--- a/includes/menu.inc	Tue Dec 23 14:28:28 2008 +0100
+++ b/includes/menu.inc	Tue Dec 23 14:29:21 2008 +0100
@@ -1,5 +1,5 @@
 <?php
-// $Id: menu.inc,v 1.255.2.7 2008/02/12 22:33:51 goba Exp $
+// $Id: menu.inc,v 1.255.2.9 2008/02/27 12:12:01 goba Exp $
 
 /**
  * @file
@@ -175,14 +175,13 @@
  * Returns the ancestors (and relevant placeholders) for any given path.
  *
  * For example, the ancestors of node/12345/edit are:
- *
- * node/12345/edit
- * node/12345/%
- * node/%/edit
- * node/%/%
- * node/12345
- * node/%
- * node
+ * - node/12345/edit
+ * - node/12345/%
+ * - node/%/edit
+ * - node/%/%
+ * - node/12345
+ * - node/%
+ * - node
  *
  * To generate these, we will use binary numbers. Each bit represents a
  * part of the path. If the bit is 1, then it represents the original
@@ -609,18 +608,18 @@
 
 /**
  * This function is similar to _menu_translate() but does link-specific
- * preparation such as always calling to_arg functions
+ * preparation such as always calling to_arg functions.
  *
  * @param $item
  *   A menu link
  * @return
  *   Returns the map of path arguments with objects loaded as defined in the
- *   $item['load_functions'].
- *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
- *   $item['href'] is generated from link_path, possibly by to_arg functions.
- *   $item['title'] is generated from link_title, and may be localized.
- *   $item['options'] is unserialized; it is also changed within the call here 
- *   to $item['localized_options'] by _menu_item_localize().
+ *   $item['load_functions']:
+ *   - $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
+ *   - $item['href'] is generated from link_path, possibly by to_arg functions.
+ *   - $item['title'] is generated from link_title, and may be localized.
+ *   - $item['options'] is unserialized; it is also changed within the call
+ *     here to $item['localized_options'] by _menu_item_localize().
  */
 function _menu_link_translate(&$item) {
   $item['options'] = unserialize($item['options']);
@@ -682,7 +681,7 @@
  *   The expected position for $type object. For node/%node this is 1, for
  *   comment/reply/%node this is 2. Defaults to 1.
  * @param $path
- *   See @menu_get_item for more on this. Defaults to the current path.
+ *   See menu_get_item() for more on this. Defaults to the current path.
  */
 function menu_get_object($type = 'node', $position = 1, $path = NULL) {
   $router_item = menu_get_item($path);
@@ -1708,8 +1707,7 @@
   }
   $placeholders = db_placeholders($menu, 'varchar');
   $paths = array_keys($menu);
-  // Updated items and customized items which router paths are gone need new
-  // router paths.
+  // Updated and customized items whose router paths are gone need new ones.
   $result = db_query("SELECT ml.link_path, ml.mlid, ml.router_path, ml.updated FROM {menu_links} ml WHERE ml.updated = 1 OR (router_path NOT IN ($placeholders) AND external = 0 AND customized = 1)", $paths);
   while ($item = db_fetch_array($result)) {
     $router_path = _menu_find_router_path($menu, $item['link_path']);
@@ -1720,7 +1718,7 @@
       db_query("UPDATE {menu_links} SET router_path = '%s', updated = %d WHERE mlid = %d", $router_path, $updated, $item['mlid']);
     }
   }
-  // Find any items where their router path does not exist any more.
+  // Find any item whose router path does not exist any more.
   $result = db_query("SELECT * FROM {menu_links} WHERE router_path NOT IN ($placeholders) AND external = 0 AND updated = 0 AND customized = 0 ORDER BY depth DESC", $paths);
   // Remove all such items. Starting from those with the greatest depth will
   // minimize the amount of re-parenting done by menu_link_delete().
@@ -1782,14 +1780,14 @@
  *
  * @param $item
  *   An array representing a menu link item. The only mandatory keys are
- *   link_path and link_title. Possible keys are
- *     menu_name   default is navigation
- *     weight      default is 0
- *     expanded    whether the item is expanded.
- *     options     An array of options, @see l for more.
- *     mlid        Set to an existing value, or 0 or NULL to insert a new link.
- *     plid        The mlid of the parent.
- *     router_path The path of the relevant router item.
+ *   link_path and link_title. Possible keys are:
+ *   - menu_name   default is navigation
+ *   - weight      default is 0
+ *   - expanded    whether the item is expanded.
+ *   - options     An array of options, @see l for more.
+ *   - mlid        Set to an existing value, or 0 or NULL to insert a new link.
+ *   - plid        The mlid of the parent.
+ *   - router_path The path of the relevant router item.
  */
 function menu_link_save(&$item) {
   $menu = menu_router_build();