From 77a67b3fed7fe815b87300937133a507bedcb037 Mon Sep 17 00:00:00 2001
From: nacin <nacin@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Tue, 18 May 2010 05:59:25 +0000
Subject: [PATCH] Inline docs for menu location functions. props jorbin, see
 #13378.

git-svn-id: http://svn.automattic.com/wordpress/trunk@14721 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/nav-menu-template.php |  3 +--
 wp-includes/nav-menu.php          | 29 ++++++++++++++++++++++-------
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/wp-includes/nav-menu-template.php b/wp-includes/nav-menu-template.php
index 0943db7b2..f83e36c66 100644
--- a/wp-includes/nav-menu-template.php
+++ b/wp-includes/nav-menu-template.php
@@ -183,8 +183,7 @@ class Walker_Nav_Menu_Checklist extends Walker_Nav_Menu  {
  * depth - how many levels of the hierarchy are to be included.  0 means all.  Defaults to 0.
  * walker - allows a custom walker to be specified.
  * context - the context the menu is used in.
- * 
- * @todo show_home - If you set this argument, then it will display the link to the home page. The show_home argument really just needs to be set to the value of the text of the link.
+ * theme_location - the location in the theme to be used.  Must be registered with register_nav_menu() in order to be selectable by the user.
  *
  * @since 3.0.0
  *
diff --git a/wp-includes/nav-menu.php b/wp-includes/nav-menu.php
index a9ba77429..58103f31e 100644
--- a/wp-includes/nav-menu.php
+++ b/wp-includes/nav-menu.php
@@ -12,8 +12,11 @@
  *
  * @since 3.0.0
  *
- * @param string $menu Menu id
- * @return mixed $menu|false Or WP_Error
+ * @uses get_term
+ * @uses get_term_by
+ *
+ * @param string $menu Menu id, slug or name
+ * @return mixed false if $menu param isn't supplied or term does not exist, menu object if successfull
  */
 function wp_get_nav_menu_object( $menu ) {
 	if ( ! $menu )
@@ -41,7 +44,7 @@ function wp_get_nav_menu_object( $menu ) {
  *
  * @since 3.0.0
  *
- * @param int|string $menu The menu to check
+ * @param int|string $menu The menu to check (id, slug, or name)
  * @return bool Whether the menu exists.
  */
 function is_nav_menu( $menu ) {
@@ -87,11 +90,23 @@ function register_nav_menus( $locations = array() ) {
 function register_nav_menu( $location, $description ) {
 	register_nav_menus( array( $location => $description ) );
 }
-
+/**
+ * Returns an array of all registered nav menus in a theme
+ *
+ * @since 3.0.0
+ * @return array
+ */
 function get_registered_nav_menus() {
 	return $GLOBALS['_wp_registered_nav_menus'];
 }
 
+/**
+ * Returns an array with the registered nav menu locations and the menu assigned to it
+ *
+ * @since 3.0.0
+ * @return array
+ */
+
 function get_nav_menu_locations() {
 	return get_theme_mod('nav_menu_locations');
 }
@@ -468,20 +483,20 @@ function wp_get_nav_menu_items( $menu, $args = array() ) {
 			$object_id = get_post_meta( $item->ID, '_menu_item_object_id', true );
 			$object = get_post_meta( $item->ID, '_menu_item_object', true );
 			$type = get_post_meta( $item->ID, '_menu_item_type', true );
-	
+
 			if ( 'post_type' == $type )
 				$posts[$object][] = $object_id;
 			elseif ( 'taxonomy' == $type)
 				$terms[$object][] = $object_id;
 		}
-	
+
 		if ( !empty($posts) ) {
 			foreach ( array_keys($posts) as $post_type ) {
 				get_posts( array('post__in' => $posts[$post_type], 'post_type' => $post_type, 'nopaging' => true, 'update_post_term_cache' => false) );
 			}
 		}
 		unset($posts);
-	
+
 		if ( !empty($terms) ) {
 			foreach ( array_keys($terms) as $taxonomy ) {
 				get_terms($taxonomy, array('include' => $terms[$taxonomy]) );