8338140: (str) Add notes to String.trim and String.isEmpty pointing to newer APIs

Reviewed-by: naoto, bpb, liach
Backport-of: 06d804a

Author: Stuart Marks

src/java.base/share/classes/java/lang/String.java

@@ -1589,6 +1589,11 @@ public int length() {
      * @return {@code true} if {@link #length()} is {@code 0}, otherwise
      * {@code false}
      *
+     * @apiNote
+     * To determine whether a string contains only
+     * {@linkplain Character#isWhitespace(int) white space}, use
+     * {@link #isBlank() isBlank}.
+     *
      * @since 1.6
      */
     @Override
@@ -3827,9 +3832,13 @@ public String toUpperCase() {
      * begins with the character at index <i>k</i> and ends with the
      * character at index <i>m</i>-that is, the result of
      * {@code this.substring(k, m + 1)}.
-     * <p>
-     * This method may be used to trim space (as defined above) from
-     * the beginning and end of a string.
+     *
+     * @apiNote
+     * This method removes leading and trailing space characters and ASCII control
+     * characters from the string. To remove characters using a Unicode-based definition of
+     * {@linkplain Character#isWhitespace(int) white space}, use {@link #strip() strip},
+     * {@link #stripIndent() stripIndent}, {@link #stripLeading() stripLeading}, or
+     * {@link #stripTrailing() stripTrailing}.
      *
      * @return  a string whose value is this string, with all leading
      *          and trailing space removed, or this string if it
@@ -3934,13 +3943,9 @@ public String stripTrailing() {
     }
 
     /**
-     * Returns {@code true} if the string is empty or contains only
-     * {@linkplain Character#isWhitespace(int) white space} codepoints,
-     * otherwise {@code false}.
-     *
-     * @return {@code true} if the string is empty or contains only
-     *         {@linkplain Character#isWhitespace(int) white space} codepoints,
-     *         otherwise {@code false}
+     * {@return {@code true} if the string is {@linkplain #isEmpty empty} or contains
+     * only {@linkplain Character#isWhitespace(int) white space} codepoints,
+     * otherwise {@code false}}
      *
      * @see Character#isWhitespace(int)
      *