Changeset 27700

Timestamp:

03/25/2014 09:03:02 AM (11 years ago)

Author:

DrewAPicture

Message:

Inline documentation for hooks in wp-includes/nav-menu.php.

Props dustyf, kpdesign.
Fixes #27367.

File:

• trunk/src/wp-includes/nav-menu.php (modified) (10 diffs)

trunk/src/wp-includes/nav-menu.php

@@ -202 +202 @@
 
     if ( $result && !is_wp_error($result) )
+
+        /**
+         * Fires after a navigation menu has been successfully deleted.
+         *
+         * @since 3.0.0
+         *
+         * @param int $term_id ID of the deleted menu.
+         */
         do_action( 'wp_delete_nav_menu', $menu->term_id );
 
@@ -214 +222 @@
  * @param int $menu_id The ID of the menu or "0" to create a new menu.
  * @param array $menu_data The array of menu data.
- * @return int|error object The menu's ID or WP_Error object.
+ * @return int|WP_Error object The menu's ID or WP_Error object.
  */
 function wp_update_nav_menu_object( $menu_id = 0, $menu_data = array() ) {
@@ -250 +258 @@
             return $_menu;
 
+        /**
+         * Fires after a navigation menu is successfully created.
+         *
+         * @since 3.0.0
+         *
+         * @param int   $term_id   ID of the new menu.
+         * @param array $menu_data An array of menu data.
+         */
         do_action( 'wp_create_nav_menu', $_menu['term_id'], $menu_data );
 
@@ -265 +281 @@
         return $update_response;
 
+    /**
+     * Fires after a navigation menu has been successfully updated.
+     *
+     * @since 3.0.0
+     *
+     * @param int   $menu_id   ID of the updated menu.
+     * @param array $menu_data An array of menu data.
+     */
     do_action( 'wp_update_nav_menu', $menu_id, $menu_data );
     return $menu_id;
@@ -412 +436 @@
     }
 
-    do_action('wp_update_nav_menu_item', $menu_id, $menu_item_db_id, $args );
+    /**
+     * Fires after a navigation menu item has been updated.
+     *
+     * @since 3.0.0
+     *
+     * @see wp_update_nav_menu_items()
+     *
+     * @param int   $menu_id         ID of the updated menu.
+     * @param int   $menu_item_db_id ID of the updated menu item.
+     * @param array $args            An array of arguments used to update a menu item.
+     */
+    do_action( 'wp_update_nav_menu_item', $menu_id, $menu_item_db_id, $args );
 
     return $menu_item_db_id;
@@ -428 +463 @@
     $defaults = array( 'hide_empty' => false, 'orderby' => 'none' );
     $args = wp_parse_args( $args, $defaults );
+
+    /**
+     * Filter the navigation menu objects being returned.
+     *
+     * @since 3.0.0
+     *
+     * @see get_terms()
+     *
+     * @param array $menus An array of menu objects.
+     * @param array $args  An array of arguments used to retrieve menu objects.
+     */
     return apply_filters( 'wp_get_nav_menus', get_terms( 'nav_menu',  $args), $args );
 }
@@ -557 +603 @@
     }
 
+    /**
+     * Filter the navigation menu items being returned.
+     *
+     * @since 3.0.0
+     *
+     * @param array  $items An array of menu item post objects.
+     * @param object $menu  The menu object.
+     * @param array  $args  An array of arguments used to retrieve menu item objects.
+     */
     return apply_filters( 'wp_get_nav_menu_items',  $items, $menu, $args );
 }
@@ -633 +688 @@
             $menu_item->target = empty( $menu_item->target ) ? get_post_meta( $menu_item->ID, '_menu_item_target', true ) : $menu_item->target;
 
+            /**
+             * Filter a navigation menu item's title attribute.
+             *
+             * @since 3.0.0
+             *
+             * @param string $item_title The menu item title attribute.
+             */
             $menu_item->attr_title = empty( $menu_item->attr_title ) ? apply_filters( 'nav_menu_attr_title', $menu_item->post_excerpt ) : $menu_item->attr_title;
 
-            if ( empty( $menu_item->description ) )
-                $menu_item->description = apply_filters( 'nav_menu_description',  wp_trim_words( $menu_item->post_content, 200 ) );
+            if ( empty( $menu_item->description ) ) {
+                /**
+                 * Filter a navigation menu item's description.
+                 *
+                 * @since 3.0.0
+                 *
+                 * @param string $description The menu item description.
+                 */
+                $menu_item->description = apply_filters( 'nav_menu_description', wp_trim_words( $menu_item->post_content, 200 ) );
+            }
 
             $menu_item->classes = empty( $menu_item->classes ) ? (array) get_post_meta( $menu_item->ID, '_menu_item_classes', true ) : $menu_item->classes;
@@ -657 +727 @@
             $menu_item->target = '';
 
+            /** This filter is documented in wp-includes/nav-menu.php */
             $menu_item->attr_title = apply_filters( 'nav_menu_attr_title', '' );
+
+            /** This filter is documented in wp-includes/nav-menu.php */
             $menu_item->description = apply_filters( 'nav_menu_description', '' );
             $menu_item->classes = array();
@@ -684 +757 @@
     }
 
+    /**
+     * Filter a navigation menu item object.
+     *
+     * @since 3.0.0
+     *
+     * @param object $menu_item The menu item object.
+     */
     return apply_filters( 'wp_setup_nav_menu_item', $menu_item );
 }