Changeset 30541 for trunk/src/wp-includes/general-template.php

Timestamp:

11/24/2014 05:38:44 AM (11 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.

File:

• trunk/src/wp-includes/general-template.php (modified) (6 diffs)

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.