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 HTML tags in several argument descriptions for `wp_link_pages()`
* Remove an HTML tag from the summary for `prepend_attachment()`
* Backtick-escape inline code in the description for `get_extended()`
* Backtick-escape inline code in the description for `get_post_type_labels()`
* Various markdown formatting in the description for `add_rewrite_endpoint()`
* Markdown-indent a code snippet in the file header for wp-includes/shortcodes.php
* Markdown-indent code snippets in the description for `add_shortcode()

Props rarst.
See #30473.

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


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

wp-includes/post-template.php

@@ -730,11 +730,11 @@ function post_password_required( $post = null ) {
  * @param string|array $args {
  *     Optional. Array or string of default arguments.
  *
- *     @type string       $before           HTML or text to prepend to each link. Default is '<p> Pages:'.
+ *     @type string       $before           HTML or text to prepend to each link. Default is `<p> Pages:`.
- *     @type string       $after            HTML or text to append to each link. Default is '</p>'.
+ *     @type string       $after            HTML or text to append to each link. Default is `</p>`.
- *     @type string       $link_before      HTML or text to prepend to each link, inside the <a> tag.
+ *     @type string       $link_before      HTML or text to prepend to each link, inside the `<a>` tag.
  *                                          Also prepended to the current item, which is not linked. Default empty.
- *     @type string       $link_after       HTML or text to append to each Pages link inside the <a> tag.
+ *     @type string       $link_after       HTML or text to append to each Pages link inside the `<a>` tag.
  *                                          Also appended to the current item, which is not linked. Default empty.
  *     @type string       $next_or_number   Indicates whether page numbers should be used. Valid values are number
  *                                          and next. Default is 'number'.
@@ -1510,7 +1510,7 @@ function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = fals
 }
 
 /**
- * Wrap attachment in <<p>> element before content.
+ * Wrap attachment in paragraph tag before content.
  *
  * @since 2.0.0
  *

wp-includes/post.php

@@ -372,8 +372,8 @@ function get_children( $args = '', $output = OBJECT ) {
  * referenced.
  *
  * The returned array has 'main', 'extended', and 'more_text' keys. Main has the text before
- * the <code><!--more--></code>. The 'extended' key has the content after the
+ * the `<!--more-->`. The 'extended' key has the content after the
- * <code><!--more--></code> comment. The 'more_text' key has the custom "Read More" text.
+ * `<!--more-->` comment. The 'more_text' key has the custom "Read More" text.
  *
  * @since 1.0.0
  *
@@ -1594,8 +1594,8 @@ function _post_type_meta_capabilities( $capabilities = null ) {
  * - singular_name - name for one object of this post type. Default is Post/Page
  * - add_new - Default is Add New for both hierarchical and non-hierarchical types.
  *             When internationalizing this string, please use a gettext context
- *             {@see http://codex.wordpress.org/I18n_for_WordPress_Developers#Disambiguation_by_context}
+ *             {@link http://codex.wordpress.org/I18n_for_WordPress_Developers#Disambiguation_by_context}
- *             matching your post type. Example: <code>_x('Add New', 'product');</code>.
+ *             matching your post type. Example: `_x( 'Add New', 'product' );`.
  * - add_new_item - Default is Add New Post/Add New Page.
  * - edit_item - Default is Edit Post/Edit Page.
  * - new_item - Default is New Post/New Page.
@@ -1606,7 +1606,7 @@ function _post_type_meta_capabilities( $capabilities = null ) {
  * - parent_item_colon - This string isn't used on non-hierarchical types. In hierarchical
  *                       ones the default is 'Parent Page:'.
  * - all_items - String for the submenu. Default is All Posts/All Pages.
- * - menu_name - Default is the same as <code>name</code>.
+ * - menu_name - Default is the same as `name`.
  *
  * Above, the first default value is for non-hierarchical post types (like posts)
  * and the second one is for hierarchical post types (like pages).

wp-includes/rewrite.php

@@ -226,22 +226,20 @@ define( 'EP_ALL', EP_PERMALINK | EP_ATTACHMENT | EP_ROOT | EP_COMMENTS | EP_SEAR
  * Adding an endpoint creates extra rewrite rules for each of the matching
  * places specified by the provided bitmask. For example:
  *
- * <code>
+ *     add_rewrite_endpoint( 'json', EP_PERMALINK | EP_PAGES );
- * add_rewrite_endpoint( 'json', EP_PERMALINK | EP_PAGES );
- * </code>
  *
  * will add a new rewrite rule ending with "json(/(.*))?/?$" for every permastruct
  * that describes a permalink (post) or page. This is rewritten to "json=$match"
  * where $match is the part of the URL matched by the endpoint regex (e.g. "foo" in
- * "<permalink>/json/foo/").
+ * "[permalink]/json/foo/").
  *
  * A new query var with the same name as the endpoint will also be created.
  *
  * When specifying $places ensure that you are using the EP_* constants (or a
  * combination of them using the bitwise OR operator) as their values are not
- * guaranteed to remain static (especially EP_ALL).
+ * guaranteed to remain static (especially `EP_ALL`).
  *
- * Be sure to flush the rewrite rules - flush_rewrite_rules() - when your plugin gets
+ * Be sure to flush the rewrite rules - {@see flush_rewrite_rules()} - when your plugin gets
  * activated and deactivated.
  *
  * @since 2.1.0

wp-includes/shortcodes.php

@@ -21,9 +21,7 @@
  *
  * To apply shortcode tags to content:
  *
- * <code>
+ *     $out = do_shortcode( $content );
- * $out = do_shortcode($content);
- * </code>
  *
  * @link http://codex.wordpress.org/Shortcode_API
  *
@@ -52,38 +50,34 @@ $shortcode_tags = array();
  *
  * Simplest example of a shortcode tag using the API:
  *
- * <code>
+ *     // [footag foo="bar"]
- * // [footag foo="bar"]
+ *     function footag_func( $atts ) {
- * function footag_func($atts) {
+ *         return "foo = {
- * 	return "foo = {$atts[foo]}";
+ *             $atts[foo]
- * }
+ *         }";
- * add_shortcode('footag', 'footag_func');
+ *     }
- * </code>
+ *     add_shortcode( 'footag', 'footag_func' );
  *
  * Example with nice attribute defaults:
  *
- * <code>
+ *     // [bartag foo="bar"]
- * // [bartag foo="bar"]
+ *     function bartag_func( $atts ) {
- * function bartag_func($atts) {
+ *         $args = shortcode_atts( array(
- * 	$args = shortcode_atts(array(
+ *             'foo' => 'no foo',
- * 		'foo' => 'no foo',
+ *             'baz' => 'default baz',
- * 		'baz' => 'default baz',
+ *         ), $atts );
- * 	), $atts);
  *
- * 	return "foo = {$args['foo']}";
+ *         return "foo = {$args['foo']}";
- * }
+ *     }
- * add_shortcode('bartag', 'bartag_func');
+ *     add_shortcode( 'bartag', 'bartag_func' );
- * </code>
  *
  * Example with enclosed content:
  *
- * <code>
+ *     // [baztag]content[/baztag]
- * // [baztag]content[/baztag]
+ *     function baztag_func( $atts, $content = '' ) {
- * function baztag_func($atts, $content='') {
+ *         return "content = $content";
- * 	return "content = $content";
+ *     }
- * }
+ *     add_shortcode( 'baztag', 'baztag_func' );
- * add_shortcode('baztag', 'baztag_func');
- * </code>
  *
  * @since 2.5.0
  *

wp-includes/version.php

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