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:
* Remove HTML tag from parameter description in `comment_form()`
* Remove HTML tag from a summary for the `comment_form_top` hook
* Markdown-indent a code snippet in the description for `get_linkobjectsbyname()`
* Markdown-indent a code snippet and format an unordered list in the description for `get_linkobjects()`
* Backtick-escape some inline code in the description for `clean_pre()`
* Remove HTML tag from the summary for the `rss_tag_pre` hook
* Various formatting fixes in the descriptions for `get_filesystem_method()` and `request_filesystem_credentials()`

Props rarst for the initial patch.
See #30473.

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


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

wp-admin/includes/file.php

@@ -868,16 +868,24 @@ function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_own
 
 /**
  * Determines which Filesystem Method to use.
- * The priority of the Transports are: Direct, SSH2, FTP PHP Extension, FTP Sockets (Via Sockets class, or fsockopen())
+ *
+ * The priority of the Transports are: Direct, SSH2, FTP PHP Extension,
+ * FTP Sockets (Via Sockets class, or `fsockopen()`).
  *
  * Note that the return value of this function can be overridden in 2 ways
- *  - By defining FS_METHOD in your <code>wp-config.php</code> file
+ *
+ *  - By defining FS_METHOD in your `wp-config.php` file
  *  - By using the filesystem_method filter
- * Valid values for these are: 'direct', 'ssh2', 'ftpext' or 'ftpsockets'
+ *
- * Plugins may also define a custom transport handler, See the WP_Filesystem function for more information.
+ * Valid values for these are: 'direct', 'ssh2', 'ftpext' or 'ftpsockets'.
+ *
+ * Plugins may also define a custom transport handler, See the WP_Filesystem
+ * function for more information.
  *
  * @since 2.5.0
  *
+ * @todo Properly mark arguments as optional.
+ *
  * @param array $args Connection details.
  * @param string $context Full path to the directory that is tested for being writable.
  * @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable.
@@ -943,14 +951,20 @@ function get_filesystem_method( $args = array(), $context = false, $allow_relaxe
 }
 
 /**
- * Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
+ * Displays a form to the user to request for their FTP/SSH details in order
+ * to connect to the filesystem.
+ *
  * All chosen/entered details are saved, Excluding the Password.
  *
- * Hostnames may be in the form of hostname:portnumber (eg: wordpress.org:2467) to specify an alternate FTP/SSH port.
+ * Hostnames may be in the form of hostname:portnumber (eg: wordpress.org:2467)
+ * to specify an alternate FTP/SSH port.
  *
- * Plugins may override this form by returning true|false via the <code>request_filesystem_credentials</code> filter.
+ * Plugins may override this form by returning true|false via the
+ * {@see 'request_filesystem_credentials'} filter.
  *
- * @since 2.5.0
+ * @since 2.5.
+ *
+ * @todo Properly mark optional arguments as such
  *
  * @param string $form_post the URL to post the form to
  * @param string $type the chosen Filesystem method in use

wp-includes/comment-template.php

@@ -2137,7 +2137,7 @@ function wp_list_comments( $args = array(), $comments = null ) {
  *     }
  *     @type string $comment_field        The comment textarea field HTML.
  *     @type string $must_log_in          HTML element for a 'must be logged in to comment' message.
- *     @type string $logged_in_as         HTML element for a 'logged in as <user>' message.
+ *     @type string $logged_in_as         HTML element for a 'logged in as [user]' message.
  *     @type string $comment_notes_before HTML element for a message displayed before the comment form.
  *                                        Default 'Your email address will not be published.'.
  *     @type string $comment_notes_after  HTML element for a message displayed after the comment form.
@@ -2246,7 +2246,7 @@ function comment_form( $args = array(), $post_id = null ) {
 					<form action="<?php echo site_url( '/wp-comments-post.php' ); ?>" method="post" id="<?php echo esc_attr( $args['id_form'] ); ?>" class="comment-form"<?php echo $html5 ? ' novalidate' : ''; ?>>
 						<?php
 						/**
-						 * Fires at the top of the comment form, inside the <form> tag.
+						 * Fires at the top of the comment form, inside the form tag.
 						 *
 						 * @since 3.0.0
 						 */

wp-includes/deprecated.php

@@ -451,12 +451,10 @@ function wp_get_linksbyname($category, $args = '') {
 /**
  * Gets an array of link objects associated with category $cat_name.
  *
- * <code>
  *     $links = get_linkobjectsbyname( 'fred' );
  *     foreach ( $links as $link ) {
  *      	echo '<li>' . $link->link_name . '</li>';
  *     }
- * </code>
  *
  * @since 1.0.1
  * @deprecated 2.1.0
@@ -485,31 +483,29 @@ function get_linkobjectsbyname($cat_name = "noname" , $orderby = 'name', $limit
  * Gets an array of link objects associated with category n.
  *
  * Usage:
- * <code>
+ *
  *     $links = get_linkobjects(1);
  *     if ($links) {
  *     	foreach ($links as $link) {
  *     		echo '<li>'.$link->link_name.'<br />'.$link->link_description.'</li>';
  *     	}
  *     }
- * </code>
  *
  * Fields are:
- * <ol>
+ *
- *	<li>link_id</li>
+ * - link_id
- *	<li>link_url</li>
+ * - link_url
- *	<li>link_name</li>
+ * - link_name
- *	<li>link_image</li>
+ * - link_image
- *	<li>link_target</li>
+ * - link_target
- *	<li>link_category</li>
+ * - link_category
- *	<li>link_description</li>
+ * - link_description
- *	<li>link_visible</li>
+ * - link_visible
- *	<li>link_owner</li>
+ * - link_owner
- *	<li>link_rating</li>
+ * - link_rating
- *	<li>link_updated</li>
+ * - link_updated
- *	<li>link_rel</li>
+ * - link_rel
- *	<li>link_notes</li>
+ * - link_notes
- * </ol>
  *
  * @since 1.0.1
  * @deprecated 2.1.0
@@ -2989,7 +2985,7 @@ function get_current_theme() {
 /**
  * Accepts matches array from preg_replace_callback in wpautop() or a string.
  *
- * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not
+ * Ensures that the contents of a `<pre>...</pre>` HTML block are not
  * converted into paragraphs or line-breaks.
  *
  * @since 1.2.0

wp-includes/feed-rss2.php

@@ -11,7 +11,7 @@ $more = 1;
 echo '<?xml version="1.0" encoding="'.get_option('blog_charset').'"?'.'>';
 
 /**
- * Fires between the <xml> and <rss> tags in a feed.
+ * Fires between the xml and rss tags in a feed.
  *
  * @since 4.0.0
  *

wp-includes/version.php

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