Improve documentation in the check_comments() docblock.

* Removes two duplicate sentences from the long description
* Tightens up phrasing elsewhere in the long description for specific checks
* Clarifies the parameter and return descriptions, and adds periods

See #29734.

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


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

wp-includes/comment.php

@@ -7,36 +7,34 @@
  */
 
 /**
- * Checks whether a comment passes internal checks to be allowed to add.
+ * Check whether a comment passes internal checks to be allowed to add.
  *
- * If comment moderation is set in the administration, then all comments,
+ * If manual comment moderation is set in the administration, then all checks,
- * regardless of their type and whitelist will be set to false. If the number of
+ * regardless of their type and whitelist, will fail and the function will
- * links exceeds the amount in the administration, then the check fails. If any
+ * return false.
- * of the parameter contents match the blacklist of words, then the check fails.
  *
  * If the number of links exceeds the amount in the administration, then the
  * check fails. If any of the parameter contents match the blacklist of words,
  * then the check fails.
  *
- * If the comment author was approved before, then the comment is
+ * If the comment author was approved before, then the comment is automatically
- * automatically whitelisted.
+ * whitelisted.
  *
- * If none of the checks fail, then the failback is to set the check to pass
+ * If all checks pass, the function will return true.
- * (return true).
  *
  * @since 1.2.0
- * @uses $wpdb
  *
- * @param string $author Comment Author's name
+ * @global wpdb $wpdb WordPress database access abstraction object.
- * @param string $email Comment Author's email
+ *
- * @param string $url Comment Author's URL
+ * @param string $author       Comment author name.
- * @param string $comment Comment contents
+ * @param string $email        Comment author email.
- * @param string $user_ip Comment Author's IP address
+ * @param string $url          Comment author URL.
- * @param string $user_agent Comment Author's User Agent
+ * @param string $comment      Content of the comment.
- * @param string $comment_type Comment type, either user submitted comment,
+ * @param string $user_ip      Comment author IP address.
- *		trackback, or pingback
+ * @param string $user_agent   Comment author User-Agent.
- * @return bool Whether the checks passed (true) and the comments should be
+ * @param string $comment_type Comment type, either user-submitted comment,
- *		displayed or set to moderated
+ *		                       trackback, or pingback.
+ * @return bool If all checks pass, true, otherwise false.
  */
 function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) {
 	global $wpdb;