Ensure inline code is markdown-escaped as such, HTML tags are removed from summaries, and that code snippets in descriptions are properly indented.

Affects DocBlocks for the following core elements:
* Backtick-escape an HTML tag in the description for the `media_upload_mime_type_links()` hook
* Backtick-escape inline code in the description for `wp_get_active_network_plugins()`
* Remove HTML tags from the summaries for the `nav_menu_css_class`, `nav_menu_item_id`, and `nav_menu_link_attributes` hooks
* Backtick-escape HTML tags, add inline `@see` tags to parameter descriptions for the `nav_menu_css_class`, `nav_menu_item_id`, and `nav_menu_link_attributes` hooks

Props rarst.
See #30473.


git-svn-id: https://develop.svn.wordpress.org/trunk@30543 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/includes/media.php

@@ -2349,7 +2349,7 @@ foreach ( $post_mime_types as $mime_type => $label ) {
 /**
  * Filter the media upload mime type list items.
  *
- * Returned values should begin with an <li> tag.
+ * Returned values should begin with an `<li>` tag.
  *
  * @since 3.1.0
  *

src/wp-includes/ms-load.php

@@ -29,12 +29,12 @@ function is_subdomain_install() {
  * Returns array of network plugin files to be included in global scope.
  *
  * The default directory is wp-content/plugins. To change the default directory
- * manually, define <code>WP_PLUGIN_DIR</code> and <code>WP_PLUGIN_URL</code>
+ * manually, define `WP_PLUGIN_DIR` and `WP_PLUGIN_URL` in `wp-config.php`.
- * in wp-config.php.
  *
  * @access private
  * @since 3.1.0
- * @return array Files to include
+ *
+ * @return array Files to include.
  */
 function wp_get_active_network_plugins() {
 	$active_plugins = (array) get_site_option( 'active_sitewide_plugins', array() );

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

@@ -85,32 +85,28 @@ class Walker_Nav_Menu extends Walker {
 		$classes[] = 'menu-item-' . $item->ID;
 
 		/**
-		 * Filter the CSS class(es) applied to a menu item's <li>.
+		 * Filter the CSS class(es) applied to a menu item's li element.
 		 *
 		 * @since 3.0.0
 		 * @since 4.1.0 The `$depth` parameter was added.
 		 *
-		 * @see wp_nav_menu()
+		 * @param array  $classes The CSS classes that are applied to the menu item's `<li>` element.
-		 *
-		 * @param array  $classes The CSS classes that are applied to the menu item's <li>.
 		 * @param object $item    The current menu item.
-		 * @param array  $args    An array of wp_nav_menu() arguments.
+		 * @param array  $args    An array of {@see wp_nav_menu()} arguments.
 		 * @param int    $depth   Depth of menu item. Used for padding.
 		 */
 		$class_names = join( ' ', (array) apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item, $args, $depth ) );
 		$class_names = $class_names ? ' class="' . esc_attr( $class_names ) . '"' : '';
 
 		/**
-		 * Filter the ID applied to a menu item's <li>.
+		 * Filter the ID applied to a menu item's li element.
 		 *
 		 * @since 3.0.1
 		 * @since 4.1.0 The `$depth` parameter was added.
 		 *
-		 * @see wp_nav_menu()
+		 * @param string $menu_id The ID that is applied to the menu item's `<li>` element.
-		 *
-		 * @param string $menu_id The ID that is applied to the menu item's <li>.
 		 * @param object $item    The current menu item.
-		 * @param array  $args    An array of wp_nav_menu() arguments.
+		 * @param array  $args    An array of {@see wp_nav_menu()} arguments.
 		 * @param int    $depth   Depth of menu item. Used for padding.
 		 */
 		$id = apply_filters( 'nav_menu_item_id', 'menu-item-'. $item->ID, $item, $args, $depth );
@@ -125,15 +121,13 @@ class Walker_Nav_Menu extends Walker {
 		$atts['href']   = ! empty( $item->url )        ? $item->url        : '';
 
 		/**
-		 * Filter the HTML attributes applied to a menu item's <a>.
+		 * Filter the HTML attributes applied to a menu item's 'a' element.
 		 *
 		 * @since 3.6.0
 		 * @since 4.1.0 The `$depth` parameter was added.
 		 *
-		 * @see wp_nav_menu()
-		 *
 		 * @param array $atts {
-		 *     The HTML attributes applied to the menu item's <a>, empty strings are ignored.
+		 *     The HTML attributes applied to the menu item's `<a>` element, empty strings are ignored.
 		 *
 		 *     @type string $title  Title attribute.
 		 *     @type string $target Target attribute.
@@ -141,7 +135,7 @@ class Walker_Nav_Menu extends Walker {
 		 *     @type string $href   The href attribute.
 		 * }
 		 * @param object $item  The current menu item.
-		 * @param array  $args  An array of wp_nav_menu() arguments.
+		 * @param array  $args  An array of {@see wp_nav_menu()} arguments.
 		 * @param int    $depth Depth of menu item. Used for padding.
 		 */
 		$atts = apply_filters( 'nav_menu_link_attributes', $atts, $item, $args, $depth );
@@ -164,18 +158,16 @@ class Walker_Nav_Menu extends Walker {
 		/**
 		 * Filter a menu item's starting output.
 		 *
-		 * The menu item's starting output only includes $args->before, the opening <a>,
+		 * The menu item's starting output only includes `$args->before`, the opening `<a>`,
-		 * the menu item's title, the closing </a>, and $args->after. Currently, there is
+		 * the menu item's title, the closing `</a>`, and `$args->after`. Currently, there is
-		 * no filter for modifying the opening and closing <li> for a menu item.
+		 * no filter for modifying the opening and closing `<li>` for a menu item.
 		 *
 		 * @since 3.0.0
 		 *
-		 * @see wp_nav_menu()
-		 *
 		 * @param string $item_output The menu item's starting HTML output.
 		 * @param object $item        Menu item data object.
 		 * @param int    $depth       Depth of menu item. Used for padding.
-		 * @param array  $args        An array of wp_nav_menu() arguments.
+		 * @param array  $args        An array of {@see wp_nav_menu()} arguments.
 		 */
 		$output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args );
 	}