Changeset 30546

Timestamp:

11/24/2014 06:30:19 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:

• Backtick-escape code snippets in the description for get_object_taxonomies()
• Backtick-escape inline code in a markdown-formatted unordered list in the description for get_taxonomy_labels()
• Remove an HTML tag from the summary for the Walker_Category_Checklist class
• Remove an HTML tag from the summary for wp_category_checklist(), various formatting
• Remove an HTML tag from the summary for wp_terms_checklist()
• Backtick-escape an HTML tag in the description for wp_popular_terms_checklist()
• Remove HTML tags from the summaries for page_template_dropdown(), parent_dropdown(), and wp_dropdown_roles()
• Backtick-escape HTML tags in a parameter description for add_settings_error()
• Various formatting in the description and summary for settings_errors()
• Markdown-indent code snippets in the descriptions for wpdb::prepare(), wpdb::insert(), wpdb::replace(), wpdb::update(), and wpdb::delete()
• Backtick-escape an HTML tag in a parameter description for login_header()
• Remove HTML tags from the summaries for the lostpassword_form and signup_header hooks

Props rarst.
See #30473.

Location:

trunk/src

Files:

• wp-admin/includes/template.php (modified) (9 diffs)
• wp-includes/taxonomy.php (modified) (3 diffs)
• wp-includes/wp-db.php (modified) (5 diffs)
• wp-login.php (modified) (2 diffs)
• wp-signup.php (modified) (1 diff)

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

@@ -14 +14 @@
 
 /**
- * Walker to output an unordered list of category checkbox <input> elements.
+ * Walker to output an unordered list of category checkbox input elements.
+ *
+ * @since 2.5.1
  *
  * @see Walker
  * @see wp_category_checklist()
  * @see wp_terms_checklist()
- * @since 2.5.1
  */
 class Walker_Category_Checklist extends Walker {
@@ -113 +114 @@
 
 /**
- * Output an unordered list of checkbox <input> elements labelled
+ * Output an unordered list of checkbox input elements labelled
  * with category names.
  *
+ * @since 2.5.1
+ *
+ * @todo Properly document optional arguments as such.
+ *
  * @see wp_terms_checklist()
- * @since 2.5.1
  *
  * @param int $post_id Mark categories associated with this post as checked. $selected_cats must not be an array.
@@ -138 +142 @@
 
 /**
- * Output an unordered list of checkbox <input> elements labelled
- * with term names. Taxonomy independent version of wp_category_checklist().
+ * Output an unordered list of checkbox input elements labelled with term names.
+ *
+ * Taxonomy independent version of {@see wp_category_checklist()}.
  *
  * @since 3.0.0
  *
- * @param int $post_id
- * @param array $args
+ * @todo Properly document optional default arguments.
+ *
+ * @param int   $post_id Post ID.
+ * @param array $args    Arguments to form the terms checklist.
  */
 function wp_terms_checklist( $post_id = 0, $args = array() ) {
@@ -237 +244 @@
  *
  * If the $echo argument is true then the elements for a list of checkbox
- * <input> elements labelled with the names of the selected terms is output.
+ * `<input>` elements labelled with the names of the selected terms is output.
  * If the $post_ID global isn't empty then the terms associated with that
  * post will be marked as checked.
@@ -783 +790 @@
 
 /**
- * Print out <option> HTML elements for the page templates drop-down.
+ * Print out option HTML elements for the page templates drop-down.
  *
  * @since 1.5.0
@@ -799 +806 @@
 
 /**
- * Print out <option> HTML elements for the page parents drop-down.
+ * Print out option HTML elements for the page parents drop-down.
  *
  * @since 1.5.0
@@ -832 +839 @@
 
 /**
- * Print out <option> html elements for role selectors
+ * Print out option html elements for role selectors.
  *
  * @since 2.1.0
@@ -1308 +1315 @@
  * @since 3.0.0
  *
+ * @todo Properly document optional arguments as such.
+ *
  * @global array $wp_settings_errors Storage array of errors registered during this pageload
  *
  * @param string $setting Slug title of the setting to which this error applies
- * @param string $code Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
- * @param string $message The formatted message text to display to the user (will be shown inside styled <div> and <p>)
- * @param string $type The type of message it is, controls HTML class. Use 'error' or 'updated'.
+ * @param string $code    Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
+ * @param string $message The formatted message text to display to the user (will be shown inside styled
+ *                        `<div>` and `<p>` tags).
+ * @param string $type    The type of message it is, controls HTML class. Use 'error' or 'updated'.
  */
 function add_settings_error( $setting, $code, $message, $type = 'error' ) {
@@ -1383 +1393 @@
 
 /**
- * Display settings errors registered by add_settings_error()
- *
- * Part of the Settings API. Outputs a <div> for each error retrieved by get_settings_errors().
- *
- * This is called automatically after a settings page based on the Settings API is submitted.
- * Errors should be added during the validation callback function for a setting defined in register_setting()
- *
- * The $sanitize option is passed into get_settings_errors() and will re-run the setting sanitization
+ * Display settings errors registered by {@see add_settings_error()}.
+ *
+ * Part of the Settings API. Outputs a div for each error retrieved by
+ * {@see get_settings_errors()}.
+ *
+ * This is called automatically after a settings page based on the
+ * Settings API is submitted. Errors should be added during the validation
+ * callback function for a setting defined in {@see register_setting()}
+ *
+ * The $sanitize option is passed into {@see get_settings_errors()} and will
+ * re-run the setting sanitization
  * on its current value.
  *
- * The $hide_on_update option will cause errors to only show when the settings page is first loaded.
- * if the user has already saved new values it will be hidden to avoid repeating messages already
- * shown in the default error reporting after submission. This is useful to show general errors like missing
- * settings when the user arrives at the settings page.
+ * The $hide_on_update option will cause errors to only show when the settings
+ * page is first loaded. if the user has already saved new values it will be
+ * hidden to avoid repeating messages already shown in the default error
+ * reporting after submission. This is useful to show general errors like
+ * missing settings when the user arrives at the settings page.
  *
  * @since 3.0.0

trunk/src/wp-includes/taxonomy.php

@@ -156 +156 @@
  * $wp_taxonomies global variable.
  *
- * <code><?php $taxonomies = get_object_taxonomies('post'); ?></code> Should
- * result in <code>Array('category', 'post_tag')</code>
+ * `<?php $taxonomies = get_object_taxonomies('post'); ?>` Should
+ * result in `Array( 'category', 'post_tag' )`
  *
  * @since 2.3.0
@@ -435 +435 @@
  *
  * Accepted keys of the label array in the taxonomy object:
+ *
  * - name - general name for the taxonomy, usually plural. The same as and overridden by $tax->label. Default is Tags/Categories
  * - singular_name - name for one object of this taxonomy. Default is Tag/Category
@@ -441 +442 @@
  * - all_items - Default is All Tags/All Categories
  * - parent_item - This string isn't used on non-hierarchical taxonomies. In hierarchical ones the default is Parent Category
- * - parent_item_colon - The same as <code>parent_item</code>, but with colon <code>:</code> in the end
+ * - parent_item_colon - The same as `parent_item`, but with colon `:ё in the end
  * - edit_item - Default is Edit Tag/Edit Category
  * - view_item - Default is View Tag/View Category

trunk/src/wp-includes/wp-db.php

@@ -1173 +1173 @@
      * Both %d and %s should be left unquoted in the query string.
      *
-     * <code>
-     * wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", 'foo', 1337 )
-     * wpdb::prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
-     * </code>
+     *     wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", 'foo', 1337 )
+     *     wpdb::prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
      *
      * @link http://php.net/sprintf Description of syntax.
@@ -1725 +1723 @@
      * Insert a row into a table.
      *
-     * <code>
-     * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
-     * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
-     * </code>
+     *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
+     *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
      *
      * @since 2.5.0
@@ -1748 +1744 @@
      * Replace a row into a table.
      *
-     * <code>
-     * wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
-     * wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
-     * </code>
+     *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
+     *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
      *
      * @since 3.0.0
@@ -1815 +1809 @@
      * Update a row in the table
      *
-     * <code>
-     * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
-     * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
-     * </code>
+     *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
+     *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
      *
      * @since 2.5.0
@@ -1869 +1861 @@
      * Delete a row in the table
      *
-     * <code>
-     * wpdb::delete( 'table', array( 'ID' => 1 ) )
-     * wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
-     * </code>
+     *     wpdb::delete( 'table', array( 'ID' => 1 ) )
+     *     wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
      *
      * @since 3.4.0

trunk/src/wp-login.php

@@ -26 +26 @@
  * Output the login page header.
  *
- * @param string   $title    Optional. WordPress Log In Page title to display in <title> element. Default 'Log In'.
+ * @param string   $title    Optional. WordPress login Page title to display in the `<title>` element.
+ *                           Default 'Log In'.
  * @param string   $message  Optional. Message to display in header. Default empty.
  * @param WP_Error $wp_error Optional. The error to pass. Default empty.
@@ -538 +539 @@
     <?php
     /**
-     * Fires inside the lostpassword <form> tags, before the hidden fields.
+     * Fires inside the lostpassword form tags, before the hidden fields.
      *
      * @since 2.1.0

trunk/src/wp-signup.php

@@ -20 +20 @@
 function do_signup_header() {
     /**
-     * Fires within the <head> section of the site sign-up screen.
+     * Fires within the head section of the site sign-up screen.
      *
      * @since 3.0.0