Changeset 30538

Timestamp:

11/24/2014 05:18:56 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:

• 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.

Location:

trunk/src

Files:

• wp-admin/includes/file.php (modified) (2 diffs)
• wp-includes/comment-template.php (modified) (2 diffs)
• wp-includes/deprecated.php (modified) (3 diffs)
• wp-includes/feed-rss2.php (modified) (1 diff)

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

@@ -869 +869 @@
 /**
  * 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.
@@ -944 +952 @@
 
 /**
- * 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.
- *
- * Plugins may override this form by returning true|false via the <code>request_filesystem_credentials</code> filter.
- *
- * @since 2.5.0
+ * 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
+ * {@see 'request_filesystem_credentials'} filter.
+ *
+ * @since 2.5.
+ *
+ * @todo Properly mark optional arguments as such
  *
  * @param string $form_post the URL to post the form to

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

@@ -2138 +2138 @@
  *     @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.'.
@@ -2247 +2247 @@
                         <?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

trunk/src/wp-includes/deprecated.php

@@ -452 +452 @@
  * 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>
+ *     $links = get_linkobjectsbyname( 'fred' );
+ *     foreach ( $links as $link ) {
+ *          echo '<li>' . $link->link_name . '</li>';
+ *     }
  *
  * @since 1.0.1
@@ -486 +484 @@
  *
  * Usage:
- * <code>
- *  $links = get_linkobjects(1);
- *  if ($links) {
- *      foreach ($links as $link) {
- *          echo '<li>'.$link->link_name.'<br />'.$link->link_description.'</li>';
- *      }
- *  }
- * </code>
+ *
+ *     $links = get_linkobjects(1);
+ *     if ($links) {
+ *      foreach ($links as $link) {
+ *          echo '<li>'.$link->link_name.'<br />'.$link->link_description.'</li>';
+ *      }
+ *     }
  *
  * Fields are:
- * <ol>
- *  <li>link_id</li>
- *  <li>link_url</li>
- *  <li>link_name</li>
- *  <li>link_image</li>
- *  <li>link_target</li>
- *  <li>link_category</li>
- *  <li>link_description</li>
- *  <li>link_visible</li>
- *  <li>link_owner</li>
- *  <li>link_rating</li>
- *  <li>link_updated</li>
- *  <li>link_rel</li>
- *  <li>link_notes</li>
- * </ol>
+ *
+ * - link_id
+ * - link_url
+ * - link_name
+ * - link_image
+ * - link_target
+ * - link_category
+ * - link_description
+ * - link_visible
+ * - link_owner
+ * - link_rating
+ * - link_updated
+ * - link_rel
+ * - link_notes
  *
  * @since 1.0.1
@@ -2990 +2986 @@
  * 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.
  *

trunk/src/wp-includes/feed-rss2.php

@@ -12 +12 @@
 
 /**
- * Fires between the <xml> and <rss> tags in a feed.
+ * Fires between the xml and rss tags in a feed.
  *
  * @since 4.0.0