Changeset 30544

Timestamp:

11/24/2014 06:04:10 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 wp_salt()
• Backtick-escape inline code in the return description for get_avatar()
• Various markdown formatting in the description for add_filter()
• Markdown-indent a code snippet in the description for apply_filters()
• Backtick-escape inline code in the @see description for apply_filters_ref_array()
• Backtick-escape inline code in the description for do_action()
• Backtick-escape variables in the parameter and return descriptions for do_action_ref_array()
• Various markdown formatting in the description for get_plugin_data()

Props rarst.
See #30473.

Location:

trunk/src

Files:

• wp-admin/includes/plugin.php (modified) (2 diffs)
• wp-includes/pluggable.php (modified) (2 diffs)
• wp-includes/plugin.php (modified) (6 diffs)

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

@@ -15 +15 @@
  * and the same goes for the plugin data. The below is formatted for printing.
  *
- * <code>
- * /*
- * Plugin Name: Name of Plugin
- * Plugin URI: Link to plugin information
- * Description: Plugin Description
- * Author: Plugin author's name
- * Author URI: Link to the author's web site
- * Version: Must be set in the plugin for WordPress 2.3+
- * Text Domain: Optional. Unique identifier, should be same as the one used in
- *      plugin_text_domain()
- * Domain Path: Optional. Only useful if the translations are located in a
- *      folder above the plugin's base path. For example, if .mo files are
- *      located in the locale folder then Domain Path will be "/locale/" and
- *      must have the first slash. Defaults to the base folder the plugin is
- *      located in.
- * Network: Optional. Specify "Network: true" to require that a plugin is activated
- *      across all sites in an installation. This will prevent a plugin from being
- *      activated on a single site when Multisite is enabled.
- *  * / # Remove the space to close comment
- * </code>
+ *     /*
+ *     Plugin Name: Name of Plugin
+ *     Plugin URI: Link to plugin information
+ *     Description: Plugin Description
+ *     Author: Plugin author's name
+ *     Author URI: Link to the author's web site
+ *     Version: Must be set in the plugin for WordPress 2.3+
+ *     Text Domain: Optional. Unique identifier, should be same as the one used in
+ *          plugin_text_domain()
+ *     Domain Path: Optional. Only useful if the translations are located in a
+ *          folder above the plugin's base path. For example, if .mo files are
+ *          located in the locale folder then Domain Path will be "/locale/" and
+ *          must have the first slash. Defaults to the base folder the plugin is
+ *          located in.
+ *     Network: Optional. Specify "Network: true" to require that a plugin is activated
+ *          across all sites in an installation. This will prevent a plugin from being
+ *          activated on a single site when Multisite is enabled.
+ *      * / # Remove the space to close comment
  *
  * Plugin data returned array contains the following:
- *      'Name' - Name of the plugin, must be unique.
- *      'Title' - Title of the plugin and the link to the plugin's web site.
- *      'Description' - Description of what the plugin does and/or notes
- *      from the author.
- *      'Author' - The author's name
- *      'AuthorURI' - The authors web site address.
- *      'Version' - The plugin version number.
- *      'PluginURI' - Plugin web site address.
- *      'TextDomain' - Plugin's text domain for localization.
- *      'DomainPath' - Plugin's relative directory path to .mo files.
- *      'Network' - Boolean. Whether the plugin can only be activated network wide.
+ *
+ * - 'Name' - Name of the plugin, must be unique.
+ * - 'Title' - Title of the plugin and the link to the plugin's web site.
+ * - 'Description' - Description of what the plugin does and/or notes
+ * - from the author.
+ * - 'Author' - The author's name
+ * - 'AuthorURI' - The authors web site address.
+ * - 'Version' - The plugin version number.
+ * - 'PluginURI' - Plugin web site address.
+ * - 'TextDomain' - Plugin's text domain for localization.
+ * - 'DomainPath' - Plugin's relative directory path to .mo files.
+ * - 'Network' - Boolean. Whether the plugin can only be activated network wide.
  *
  * Some users have issues with opening large files and manipulating the contents
@@ -63 +62 @@
  * @link https://core.trac.wordpress.org/ticket/5651 Previous Optimizations.
  * @link https://core.trac.wordpress.org/ticket/7372 Further and better Optimizations.
+ *
  * @since 1.5.0
  *

trunk/src/wp-includes/pluggable.php

@@ -1773 +1773 @@
  * for you.
  *
- * <code>
- * define('AUTH_KEY',         ' Xakm<o xQy rw4EMsLKM-?!T+,PFF})H4lzcW57AF0U@N@< >M%G4Yt>f`z]MON');
- * define('SECURE_AUTH_KEY',  'LzJ}op]mr|6+![P}Ak:uNdJCJZd>(Hx.-Mh#Tz)pCIU#uGEnfFz|f ;;eU%/U^O~');
- * define('LOGGED_IN_KEY',    '|i|Ux`9<p-h$aFf(qnT:sDO:D1P^wZ$$/Ra@miTJi9G;ddp_<q}6H1)o|a +&JCM');
- * define('NONCE_KEY',        '%:R{[P|,s.KuMltH5}cI;/k<Gx~j!f0I)m_sIyu+&NJZ)-iO>z7X>QYR0Z_XnZ@|');
- * define('AUTH_SALT',        'eZyT)-Naw]F8CwA*VaW#q*|.)g@o}||wf~@C-YSt}(dh_r6EbI#A,y|nU2{B#JBW');
- * define('SECURE_AUTH_SALT', '!=oLUTXh,QW=H `}`L|9/^4-3 STz},T(w}W<I`.JjPi)<Bmf1v,HpGe}T1:Xt7n');
- * define('LOGGED_IN_SALT',   '+XSqHc;@Q*K_b|Z?NC[3H!!EONbh.n<+=uKR:>*c(u`g~EJBf#8u#R{mUEZrozmm');
- * define('NONCE_SALT',       'h`GXHhD>SLWVfg1(1(N{;.V!MoE(SfbA_ksP@&`+AycHcAV$+?@3q+rxV{%^VyKT');
- * </code>
+ *     define('AUTH_KEY',         ' Xakm<o xQy rw4EMsLKM-?!T+,PFF})H4lzcW57AF0U@N@< >M%G4Yt>f`z]MON');
+ *     define('SECURE_AUTH_KEY',  'LzJ}op]mr|6+![P}Ak:uNdJCJZd>(Hx.-Mh#Tz)pCIU#uGEnfFz|f ;;eU%/U^O~');
+ *     define('LOGGED_IN_KEY',    '|i|Ux`9<p-h$aFf(qnT:sDO:D1P^wZ$$/Ra@miTJi9G;ddp_<q}6H1)o|a +&JCM');
+ *     define('NONCE_KEY',        '%:R{[P|,s.KuMltH5}cI;/k<Gx~j!f0I)m_sIyu+&NJZ)-iO>z7X>QYR0Z_XnZ@|');
+ *     define('AUTH_SALT',        'eZyT)-Naw]F8CwA*VaW#q*|.)g@o}||wf~@C-YSt}(dh_r6EbI#A,y|nU2{B#JBW');
+ *     define('SECURE_AUTH_SALT', '!=oLUTXh,QW=H `}`L|9/^4-3 STz},T(w}W<I`.JjPi)<Bmf1v,HpGe}T1:Xt7n');
+ *     define('LOGGED_IN_SALT',   '+XSqHc;@Q*K_b|Z?NC[3H!!EONbh.n<+=uKR:>*c(u`g~EJBf#8u#R{mUEZrozmm');
+ *     define('NONCE_SALT',       'h`GXHhD>SLWVfg1(1(N{;.V!MoE(SfbA_ksP@&`+AycHcAV$+?@3q+rxV{%^VyKT');
  *
  * Salting passwords helps against tools which has stored hashed values of
@@ -2091 +2089 @@
  * @param string $default URL to a default image to use if no avatar is available
  * @param string $alt Alternative text to use in image tag. Defaults to blank
- * @return string <img> tag for the user's avatar
+ * @return string `<img>` tag for the user's avatar.
 */
 function get_avatar( $id_or_email, $size = '96', $default = '', $alt = false ) {

trunk/src/wp-includes/plugin.php

@@ -46 +46 @@
  *
  * The following example shows how a callback function is bound to a filter hook.
- * Note that $example is passed to the callback, (maybe) modified, then returned:
- *
- * <code>
- * function example_callback( $example ) {
- *  // Maybe modify $example in some way
- *  return $example;
- * }
- * add_filter( 'example_filter', 'example_callback' );
- * </code>
+ *
+ * Note that `$example` is passed to the callback, (maybe) modified, then returned:
+ *
+ *     function example_callback( $example ) {
+ *         // Maybe modify $example in some way.
+ *         return $example;
+ *     }
+ *     add_filter( 'example_filter', 'example_callback' );
  *
  * Since WordPress 1.5.1, bound callbacks can take as many arguments as are
- * passed as parameters in the corresponding apply_filters() call. The $accepted_args
+ * passed as parameters in the corresponding apply_filters() call. The `$accepted_args`
  * parameter allows for calling functions only when the number of args match.
  *
- * <strong>Note:</strong> the function will return true whether or not the callback
- * is valid. It is up to you to take care. This is done for optimization purposes,
+ * *Note:* the function will return true whether or not the callback is valid.
+ * It is up to you to take care. This is done for optimization purposes,
  * so everything is as quick as possible.
  *
@@ -149 +148 @@
  *
  * The function allows for additional arguments to be added and passed to hooks.
- * <code>
- * // Our filter callback function
- * function example_callback( $string, $arg1, $arg2 ) {
- *  // (maybe) modify $string
- *  return $string;
- * }
- * add_filter( 'example_filter', 'example_callback', 10, 3 );
- *
- * // Apply the filters by calling the 'example_callback' function we
- * // "hooked" to 'example_filter' using the add_filter() function above.
- * // - 'example_filter' is the filter hook $tag
- * // - 'filter me' is the value being filtered
- * // - $arg1 and $arg2 are the additional arguments passed to the callback.
- * $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );
- * </code>
+ *
+ *     // Our filter callback function
+ *     function example_callback( $string, $arg1, $arg2 ) {
+ *         // (maybe) modify $string
+ *         return $string;
+ *     }
+ *     add_filter( 'example_filter', 'example_callback', 10, 3 );
+ *
+ *     /*
+ *      * Apply the filters by calling the 'example_callback' function we
+ *      * "hooked" to 'example_filter' using the add_filter() function above.
+ *      * - 'example_filter' is the filter hook $tag
+ *      * - 'filter me' is the value being filtered
+ *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
+ *     $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );
  *
  * @since 0.71
@@ -172 +171 @@
  *
  * @param string $tag   The name of the filter hook.
- * @param mixed  $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
- * @param mixed  $var   Additional variables passed to the functions hooked to <tt>$tag</tt>.
+ * @param mixed  $value The value on which the filters hooked to `$tag` are applied on.
+ * @param mixed  $var   Additional variables passed to the functions hooked to `$tag`.
  * @return mixed The filtered value after all hooked functions are applied to it.
  */
@@ -225 +224 @@
  * Execute functions hooked on a specific filter hook, specifying arguments in an array.
  *
+ * @see 3.0.0
+ *
  * @see apply_filters() This function is identical, but the arguments passed to the
- * functions hooked to <tt>$tag</tt> are supplied using an array.
- *
- * @since 3.0.0
+ * functions hooked to `$tag` are supplied using an array.
  *
  * @global array $wp_filter         Stores all of the filters
@@ -435 +434 @@
  * Execute functions hooked on a specific action hook.
  *
- * This function invokes all functions attached to action hook $tag. It is
+ * This function invokes all functions attached to action hook `$tag`. It is
  * possible to create new action hooks by simply calling this function,
- * specifying the name of the new hook using the <tt>$tag</tt> parameter.
+ * specifying the name of the new hook using the `$tag` parameter.
  *
  * You can pass extra arguments to the hooks, much like you can with
- * apply_filters().
+ * {@see apply_filters()}.
  *
  * @since 1.2.0
  *
- * @see apply_filters() This function works similar with the exception that nothing
- *                      is returned and only the functions or methods are called.
  * @global array $wp_filter  Stores all of the filters
  * @global array $wp_actions Increments the amount of times action was triggered.
@@ -534 +531 @@
  *
  * @param string $tag  The name of the action to be executed.
- * @param array  $args The arguments supplied to the functions hooked to <tt>$tag</tt>
- * @return null Will return null if $tag does not exist in $wp_filter array
+ * @param array  $args The arguments supplied to the functions hooked to `$tag`.
+ * @return null Will return null if `$tag` does not exist in `$wp_filter` array.
  */
 function do_action_ref_array($tag, $args) {