From de7499f88fb4984fe3d972db80813a904fb9f274 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <info@drewapicture.com>
Date: Sun, 25 Jun 2017 19:37:39 +0000
Subject: [PATCH] Docs: Add full documentation for arguments accepted by
 `wp_get_nav_menu_items()`.

Also provide differentiation between arguments as passed to `get_posts()` vs used for ordering outputted menu items.

By and large, arguments in the `$args` array are intended to directly affect how nav_menu_item posts are retrieved. When the default ARRAY_A is used for 'output', the 'order' and 'orderby' arguments are essentially ignored, instead giving preference to a hard-coded order of 'ASC' and an orderby value derived from the non-get_posts() argument 'output_key'.

Fixes #15533.

Built from https://develop.svn.wordpress.org/trunk@40942


git-svn-id: http://core.svn.wordpress.org/trunk@40792 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/nav-menu.php | 24 ++++++++++++++++++++++--
 wp-includes/version.php  |  2 +-
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/wp-includes/nav-menu.php b/wp-includes/nav-menu.php
index 2177d6af57..c3a114fd09 100644
--- a/wp-includes/nav-menu.php
+++ b/wp-includes/nav-menu.php
@@ -574,7 +574,12 @@ function _is_valid_nav_menu_item( $item ) {
 }
 
 /**
- * Return all menu items of a navigation menu.
+ * Retrieves all menu items of a navigation menu.
+ *
+ * Note: Most arguments passed to the `$args` parameter – save for 'output_key' – are
+ * specifically for retrieving nav_menu_item posts from get_posts() and may only
+ * indirectly affect the ultimate ordering and content of the resulting nav menu
+ * items that get returned from this function.
  *
  * @since 3.0.0
  *
@@ -582,7 +587,22 @@ function _is_valid_nav_menu_item( $item ) {
  * @staticvar array $fetched
  *
  * @param string $menu Menu name, ID, or slug.
- * @param array  $args Optional. Arguments to pass to get_posts().
+ * @param array  $args {
+ *     Optional. Arguments to pass to get_posts().
+ *
+ *     @type string $order       How to order nav menu items as queried with get_posts(). Will be ignored
+ *                               if 'output' is ARRAY_A. Default 'ASC'.
+ *     @type string $orderby     Field to order menu items by as retrieved from get_posts(). Supply an orderby
+ *                               field via 'output_key' to affect the output order of nav menu items.
+ *                               Default 'menu_order'.
+ *     @type string $post_type   Menu items post type. Default 'nav_menu_item'.
+ *     @type string $post_status Menu items post status. Default 'publish'.
+ *     @type string $output      How to order outputted menu items. Default ARRAY_A.
+ *     @type string $output_key  Key to use for ordering the actual menu items that get returned. Note that
+ *                               that is not a get_posts() argument and will only affect output of menu items
+ *                               processed in this function. Default 'menu_order'.
+ *     @type bool   $nopaging    Whether to retrieve all menu items (true) or paginate (false). Default true.
+ * }
  * @return false|array $items Array of menu items, otherwise false.
  */
 function wp_get_nav_menu_items( $menu, $args = array() ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 8449bc8d49..f5625283ca 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-alpha-40941';
+$wp_version = '4.9-alpha-40942';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.