8289252: Recommend Locale.of() method instead of the constructor

Reviewed-by: joehw, rriggs

src/java.base/share/classes/java/util/Locale.java

@@ -2585,34 +2585,35 @@ public final class Locale implements Cloneable, Serializable {
     /**
      * {@code Builder} is used to build instances of {@code Locale}
      * from values configured by the setters.  Unlike the {@code Locale}
-     * constructors, the {@code Builder} checks if a value configured by a
+     * constructors or {@code Locale.of()} factory methods,
+     * the {@code Builder} checks if a value configured by a
      * setter satisfies the syntax requirements defined by the {@code Locale}
      * class.  A {@code Locale} object obtained from a {@code Builder} is
      * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
      * without losing information.
      *
-     * <p><b>Note:</b> The {@code Locale} class does not provide any
+     * @implNote
+     * The {@code Locale} class does not provide any
      * syntactic restrictions on variant, while BCP 47 requires each variant
      * subtag to be 5 to 8 alphanumerics or a single numeric followed by 3
      * alphanumerics.  The method {@code setVariant} throws
      * {@code IllformedLocaleException} for a variant that does not satisfy
-     * this restriction. If it is necessary to support such a variant, use a
-     * Locale constructor.  However, keep in mind that a {@code Locale}
+     * this restriction. If it is necessary to support such a variant, use
+     * {@link Locale#of(String, String, String)}.  However, keep in mind that a {@code Locale}
      * object obtained this way might lose the variant information when
      * transformed to a BCP 47 language tag.
      *
      * <p>The following example shows how to obtain a {@code Locale} object
      * using a {@code Builder}.
-     * <blockquote>
-     * <pre>
-     *     Locale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
-     * </pre>
-     * </blockquote>
+     * {@snippet lang=java :
+     * Locale aLocale = new Locale.Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
+     * }
      *
      * <p>Builders can be reused; {@code clear()} resets all
      * fields to their default values.
      *
      * @see Locale#forLanguageTag
+     * @see Locale#of(String, String, String)
      * @since 1.7
      */
     public static final class Builder {
@@ -2763,11 +2764,12 @@ public final class Locale implements Cloneable, Serializable {
          * the {@code Locale} class does not impose any syntactic
          * restriction on variant, and the variant value in
          * {@code Locale} is case sensitive.  To set such a variant,
-         * use a Locale constructor.
+         * use {@link Locale#of(String, String, String)}.
          *
          * @param variant the variant
          * @return This builder.
          * @throws IllformedLocaleException if {@code variant} is ill-formed
+         * @see Locale#of(String, String, String)
          */
         public Builder setVariant(String variant) {
             try {