docs: document behavior of CHAR() comparisons with chars < space

Space trimming rather than space-padding causes unusual behavior, which
might not be standards-compliant.

Also remove recently-added now-redundant C comment.

doc/src/sgml/datatype.sgml

@@ -1078,10 +1078,13 @@ SELECT '52093.89'::money::numeric::float8;
    <para>
     Values of type <type>character</type> are physically padded
     with spaces to the specified width <replaceable>n</>, and are
-    stored and displayed that way.  However, the padding spaces are
-    treated as semantically insignificant.  Trailing spaces are
-    disregarded when comparing two values of type <type>character</type>,
-    and they will be removed when converting a <type>character</type> value
+    stored and displayed that way.  However, trailing spaces are treated as
+    semantically insignificant and disregarded when comparing two values
+    of type <type>character</type>.  In collations where whitespace
+    is significant, this behavior can produce unexpected results,
+    e.g. <command>SELECT 'a '::CHAR(2) collate "C" < 'a\n'::CHAR(2)
+    returns true.
+    Trailing spaces are removed when converting a <type>character</type> value
     to one of the other string types.  Note that trailing spaces
     <emphasis>are</> semantically significant in
     <type>character varying</type> and <type>text</type> values, and

src/backend/utils/adt/varchar.c

@@ -846,18 +846,6 @@ bpcharcmp(PG_FUNCTION_ARGS)
 				len2;
 	int			cmp;
 
-	/*
-	 * Trimming trailing spaces off of both strings can cause a string
-	 * with a character less than a space to compare greater than a
-	 * space-extended string, e.g. this returns false:
-	 *		SELECT E'ab\n'::CHAR(10) < E'ab '::CHAR(10);
-	 * even though '\n' is less than the space if CHAR(10) was
-	 * space-extended.  The correct solution would be to trim only
-	 * the longer string to be the same length of the shorter, if
-	 * possible, then do the comparison.  However, changing this
-	 * might break existing indexes, breaking binary upgrades.
-	 * For details, see http://www.postgresql.org/message-id/CAK+WP1xdmyswEehMuetNztM4H199Z1w9KWRHVMKzyyFM+hV=zA@mail.gmail.com
-	 */
 	len1 = bcTruelen(arg1);
 	len2 = bcTruelen(arg2);