From dd25a715b22705176601452c2f9d38334f450747 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <info@drewapicture.com>
Date: Tue, 23 Sep 2014 18:49:17 +0000
Subject: [PATCH] Improve and clarify inline commenting inside the
 `check_comment()` function.

Adds logical explanations of what some of the various comment checks are checking for, as well as some general cleanup and syntax fixes.

Fixes #29734.

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


git-svn-id: http://core.svn.wordpress.org/trunk@29535 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/comment.php | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index c7f98d124c..595f0e8ebc 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -39,15 +39,17 @@
 function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) {
 	global $wpdb;
 
+	// If manual moderation is enabled, skip all checks and return false.
 	if ( 1 == get_option('comment_moderation') )
-		return false; // If moderation is set to manual
+		return false;
 
 	/** This filter is documented in wp-includes/comment-template.php */
 	$comment = apply_filters( 'comment_text', $comment );
 
-	// Check # of external links
+	// Check for the number of external links if a max allowed number is set.
 	if ( $max_links = get_option( 'comment_max_links' ) ) {
 		$num_links = preg_match_all( '/<a [^>]*href/i', $comment, $out );
+
 		/**
 		 * Filter the maximum number of links allowed in a comment.
 		 *
@@ -57,25 +59,38 @@ function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $
 		 * @param string $url       Comment author's URL. Included in allowed links total.
 		 */
 		$num_links = apply_filters( 'comment_max_links_url', $num_links, $url );
+
+		/*
+		 * If the number of links in the comment exceeds the allowed amount,
+		 * fail the check by returning false.
+		 */
 		if ( $num_links >= $max_links )
 			return false;
 	}
 
 	$mod_keys = trim(get_option('moderation_keys'));
+
+	// If moderation 'keys' (keywords) are set, process them.
 	if ( !empty($mod_keys) ) {
 		$words = explode("\n", $mod_keys );
 
 		foreach ( (array) $words as $word) {
 			$word = trim($word);
 
-			// Skip empty lines
+			// Skip empty lines.
 			if ( empty($word) )
 				continue;
 
-			// Do some escaping magic so that '#' chars in the
-			// spam words don't break things:
+			/*
+			 * Do some escaping magic so that '#' (number of) characters in the spam
+			 * words don't break things:
+			 */
 			$word = preg_quote($word, '#');
 
+			/*
+			 * Check the comment fields for moderation keywords. If any are found,
+			 * fail the check for the given field by returning false.
+			 */
 			$pattern = "#$word#i";
 			if ( preg_match($pattern, $author) ) return false;
 			if ( preg_match($pattern, $email) ) return false;
@@ -86,7 +101,13 @@ function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $
 		}
 	}
 
-	// Comment whitelisting:
+	/*
+	 * Check if the option to approve comments by previously-approved authors is enabled.
+	 *
+	 * If it is enabled, check whether the comment author has a previously-approved comment,
+	 * as well as whether there are any moderation keywords (if set) present in the author
+	 * email address. If both checks pass, return true. Otherwise, return false.
+	 */
 	if ( 1 == get_option('comment_whitelist')) {
 		if ( 'trackback' != $comment_type && 'pingback' != $comment_type && $author != '' && $email != '' ) {
 			// expected_slashed ($author, $email)