Summary

Add notes and cross references to String.trim, String.stripX, String.isBlank, and String.isEmpty.

Problem

String.trim uses an ASCII-based definition of white space that is to be trimmed. It should have a note that mentions the String.strip family of methods, which use a Unicode-based definition of white space.

The String.isEmpty and String.isBlank method names sound very similar. They should have notes cross-linking them that clarify their distinct functions.

Solution

Update the specifications to add the appropriate notes.

Specification

Diffs to various javadoc comments in src/java.base/share/classes/java/lang/String.java:

     /**
      * Returns {@code true} if, and only if, {@link #length()} is {@code 0}.
      *
      * @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
     public boolean isEmpty() {

...

      * <p>
      * Otherwise, let <i>k</i> be the index of the first character in the
      * string whose code is not a space (as defined above) and let
      * <i>m</i> be the index of the last character in the string whose code
      * is not a space (as defined above). A {@code String}
      * object is returned, representing the substring of this string that
      * 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
      *          has no leading or trailing space.
      */
     public String trim() {

...

     /**
-     * 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)
      *
      * @since 11
      */
     public boolean isBlank() {