Changeset 30541

Timestamp:

11/24/2014 05:38:44 AM (10 years ago)

Author:

DrewAPicture

Message:

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.

Location:

trunk/src

Files:

• wp-admin/index.php (modified) (1 diff)
• wp-includes/functions.php (modified) (1 diff)
• wp-includes/functions.wp-scripts.php (modified) (2 diffs)
• wp-includes/general-template.php (modified) (6 diffs)

trunk/src/wp-admin/index.php

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

trunk/src/wp-includes/functions.php

@@ -3446 +3446 @@
  * used by comparing it to its default value or evaluating whether it is empty.
  * For example:
- * <code>
- * if ( ! empty( $deprecated ) ) {
- *  _deprecated_argument( __FUNCTION__, '3.0' );
- * }
- * </code>
+ *
+ *     if ( ! empty( $deprecated ) ) {
+ *         _deprecated_argument( __FUNCTION__, '3.0' );
+ *     }
+ *
  *
  * There is a hook deprecated_argument_run that will be called that can be used

trunk/src/wp-includes/functions.wp-scripts.php

@@ -91 +91 @@
  *
  * Accepts an associative array $l10n and creates a JavaScript object:
- * <code>
- * "$object_name" = {
- *       key: value,
- *       key: value,
- *       ...
- * }
- * </code>
+ *
+ *     "$object_name" = {
+ *         key: value,
+ *         key: value,
+ *         ...
+ *     }
+ *
  *
  * @see WP_Dependencies::localize()
@@ -104 +104 @@
  *
  * @since 2.6.0
+ *
+ * @todo Documentation cleanup
  *
  * @param string $handle      Script handle the data will be attached to.

trunk/src/wp-includes/general-template.php

@@ -512 +512 @@
  * @since 1.5.0
  *
- * @param string $before Text to output before the link (defaults to <li>).
- * @param string $after Text to output after 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. Default `</li>`.
  * @param boolean $echo Default to echo and not return the link.
  * @return string|null String when retrieving, null when displaying.
@@ -582 +582 @@
  *
  * Some show parameter values are deprecated and will be removed in future
- * versions. These options will trigger the _deprecated_argument() function.
- * The deprecated blog info options are listed in the function contents.
+ * versions. These options will trigger the {@see _deprecated_argument()}
+ * 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>
- * <li><strong>wpurl</strong> - Blog URI path to WordPress.</li>
- * <li><strong>description</strong> - Secondary title</li>
- * </ol>
+ *
+ * 1. url - Blog URI to homepage.
+ * 2. wpurl - Blog URI path to WordPress.
+ * 3. description - Secondary title
  *
  * The feed URL options can be retrieved from 'rdf_url' (RSS 0.91),
@@ -715 +715 @@
 
 /**
- * Display <title> tag with contents.
+ * Display title tag with contents.
  *
  * @since 4.1.0
@@ -1234 +1234 @@
  * 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 +1251 @@
  *
  * @since 1.0.0
+ *
+ * @todo Properly document optional arguments as such
  *
  * @param string $url URL to archive.
@@ -2707 +2709 @@
  *
  * 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"),
- * array('#07273E', '#14568A', '#D54E21', '#2683AE'));
- * </code>
+ *
+ *     wp_admin_css_color( 'classic', __( 'Classic' ), admin_url( "css/colors-classic.css" ), array(
+ *         '#07273E', '#14568A', '#D54E21', '#2683AE'
+ *     ) );
  *
  * @since 2.5.0
+ *
+ * @todo Properly document optional arguments as such
  *
  * @param string $key The unique key for this theme.