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:
* Markdown-indent a code snippet in the description for `_deprecated_argument()`
* Markdown-indent a code snippet in the description for `wp_localize_script()`
* Backtick-escape HTML tags in two parameter descriptions for `wp_register()`
* Various DocBlock formatting in the description for `get_bloginfo()`
* Remove HTML tag from the summary for `_wp_render_title_tag()`
* Backtick-escape a HTML tag in the description for `get_archives_link()`
* Markdown-indent a code snippet in the description for `wp_admin_css_color()`
* Markdown-indent a code snippet in the description for the `welcome_panel` hook

Props rarst.
See #30473.

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


git-svn-id: http://core.svn.wordpress.org/trunk@30530 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/index.php

@@ -111,8 +111,9 @@ include( ABSPATH . 'wp-admin/admin-header.php' );
 		/**
 		 * Add content to the welcome panel on the admin dashboard.
 		 *
-		 * To remove the default welcome panel, use remove_action():
+		 * To remove the default welcome panel, use {@see remove_action()}:
-		 * <code>remove_action( 'welcome_panel', 'wp_welcome_panel' );</code>
+		 *
+		 *     remove_action( 'welcome_panel', 'wp_welcome_panel' );
 		 *
 		 * @since 3.5.0
 		 */

wp-includes/functions.php

@@ -3445,11 +3445,11 @@ function _deprecated_file( $file, $version, $replacement = null, $message = '' )
  * Before this function is called, the argument must be checked for whether it was
  * used by comparing it to its default value or evaluating whether it is empty.
  * For example:
- * <code>
+ *
- * if ( ! empty( $deprecated ) ) {
+ *     if ( ! empty( $deprecated ) ) {
- * 	_deprecated_argument( __FUNCTION__, '3.0' );
+ *         _deprecated_argument( __FUNCTION__, '3.0' );
- * }
+ *     }
- * </code>
+ *
  *
  * There is a hook deprecated_argument_run that will be called that can be used
  * to get the backtrace up to what file and function used the deprecated

wp-includes/functions.wp-scripts.php

@@ -90,13 +90,13 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_f
  * Works only if the script has already been added.
  *
  * Accepts an associative array $l10n and creates a JavaScript object:
- * <code>
+ *
- * "$object_name" = {
+ *     "$object_name" = {
- *       key: value,
+ *         key: value,
- *       key: value,
+ *         key: value,
- *       ...
+ *         ...
- * }
+ *     }
- * </code>
+ *
  *
  * @see WP_Dependencies::localize()
  * @link https://core.trac.wordpress.org/ticket/11520
@@ -104,6 +104,8 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_f
  *
  * @since 2.6.0
  *
+ * @todo Documentation cleanup
+ *
  * @param string $handle      Script handle the data will be attached to.
  * @param string $object_name Name for the JavaScript object. Passed directly, so it should be qualified JS variable.
  *                            Example: '/[a-zA-Z0-9_]+/'.

wp-includes/general-template.php

@@ -511,8 +511,8 @@ function wp_lostpassword_url( $redirect = '' ) {
  *
  * @since 1.5.0
  *
- * @param string $before Text to output before the link (defaults to <li>).
+ * @param string $before Text to output before the link. Default `<li>`.
- * @param string $after Text to output after the link (defaults to </li>).
+ * @param string $after Text to output after the link. Default `</li>`.
  * @param boolean $echo Default to echo and not return the link.
  * @return string|null String when retrieving, null when displaying.
  */
@@ -581,15 +581,15 @@ function bloginfo( $show='' ) {
  * Retrieve information about the blog.
  *
  * Some show parameter values are deprecated and will be removed in future
- * versions. These options will trigger the _deprecated_argument() function.
+ * versions. These options will trigger the {@see _deprecated_argument()}
- * The deprecated blog info options are listed in the function contents.
+ * function. The deprecated blog info options are listed in the function
+ * contents.
  *
  * The possible values for the 'show' parameter are listed below.
- * <ol>
+ *
- * <li><strong>url</strong> - Blog URI to homepage.</li>
+ * 1. url - Blog URI to homepage.
- * <li><strong>wpurl</strong> - Blog URI path to WordPress.</li>
+ * 2. wpurl - Blog URI path to WordPress.
- * <li><strong>description</strong> - Secondary title</li>
+ * 3. description - Secondary title
- * </ol>
  *
  * The feed URL options can be retrieved from 'rdf_url' (RSS 0.91),
  * 'rss_url' (RSS 1.0), 'rss2_url' (RSS 2.0), or 'atom_url' (Atom feed). The
@@ -714,7 +714,7 @@ function get_bloginfo( $show = '', $filter = 'raw' ) {
 }
 
 /**
- * Display <title> tag with contents.
+ * Display title tag with contents.
  *
  * @since 4.1.0
  * @access private
@@ -1233,7 +1233,7 @@ function get_the_archive_description() {
  * elements). Custom content is also supported using the before and after
  * parameters.
  *
- * The 'link' format uses the link HTML element with the <em>archives</em>
+ * The 'link' format uses the `<link>` HTML element with the **archives**
  * relationship. The before and after parameters are not used. The text
  * parameter is used to describe the link.
  *
@@ -1251,6 +1251,8 @@ function get_the_archive_description() {
  *
  * @since 1.0.0
  *
+ * @todo Properly document optional arguments as such
+ *
  * @param string $url URL to archive.
  * @param string $text Archive text description.
  * @param string $format Optional, default is 'html'. Can be 'link', 'option', 'html', or custom.
@@ -2706,13 +2708,15 @@ function paginate_links( $args = '' ) {
  * Registers an admin colour scheme css file.
  *
  * Allows a plugin to register a new admin colour scheme. For example:
- * <code>
+ *
- * wp_admin_css_color('classic', __('Classic'), admin_url("css/colors-classic.css"),
+ *     wp_admin_css_color( 'classic', __( 'Classic' ), admin_url( "css/colors-classic.css" ), array(
- * array('#07273E', '#14568A', '#D54E21', '#2683AE'));
+ *         '#07273E', '#14568A', '#D54E21', '#2683AE'
- * </code>
+ *     ) );
  *
  * @since 2.5.0
  *
+ * @todo Properly document optional arguments as such
+ *
  * @param string $key The unique key for this theme.
  * @param string $name The name of the theme.
  * @param string $url The url of the css file containing the colour scheme.

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.1-beta2-30540';
+$wp_version = '4.1-beta2-30541';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.