Summary

Add apiNote and implSpec tags to the java.text.DecimaFormat API where applicable.

Problem

There is specification in DecimalFormat that could be better documented with the implSpec and apiNote Javadoc tags. Mainly, the wording in the DecimalFormat constructors recommending to use the NumberFormat factory methods for a standard formatting. This is better tagged as an apiNote rather than included as the API specification.

Solution

Prepend with an apiNote or implSpec tag to the wording of the affected constructors/methods.

Specification

In DecimalFormat(),

-     * <p>
-     * To obtain standard formats for a given locale, use the factory methods
-     * on NumberFormat such as getNumberInstance. These factories will
-     * return the most appropriate sub-class of NumberFormat for a given
-     * locale.
      *
-     * @see java.text.NumberFormat#getInstance
-     * @see java.text.NumberFormat#getNumberInstance
-     * @see java.text.NumberFormat#getCurrencyInstance
-     * @see java.text.NumberFormat#getPercentInstance
+     * @apiNote To obtain standard formats for a given locale, use the
+     * {@code NumberFormat} factory methods such as {@link
+     * NumberFormat#getNumberInstance(Locale)}. These factories will return the most
+     * appropriate subclass of NumberFormat for a given locale.
+     * @see NumberFormat#getInstance(Locale)
+     * @see NumberFormat#getNumberInstance(Locale)
+     * @see NumberFormat#getCurrencyInstance(Locale)
+     * @see NumberFormat#getPercentInstance(Locale)
      */

In DecimalFormat(String pattern),

-     * <p>
-     * To obtain standard formats for a given locale, use the factory methods
-     * on NumberFormat such as getNumberInstance. These factories will
-     * return the most appropriate sub-class of NumberFormat for a given
-     * locale.
      *
+     * @apiNote To obtain standard formats for a given locale, use the
+     * {@code NumberFormat} factory methods such as {@link
+     * NumberFormat#getNumberInstance(Locale)}. These factories will return the most
+     * appropriate subclass of NumberFormat for a given locale.
      * @param pattern a non-localized pattern string.
      * @throws    NullPointerException if {@code pattern} is null
      * @throws    IllegalArgumentException if the given pattern is invalid.
-     * @see java.text.NumberFormat#getInstance
-     * @see java.text.NumberFormat#getNumberInstance
-     * @see java.text.NumberFormat#getCurrencyInstance
-     * @see java.text.NumberFormat#getPercentInstance
+     * @see NumberFormat#getInstance(Locale)
+     * @see NumberFormat#getNumberInstance(Locale)
+     * @see NumberFormat#getCurrencyInstance(Locale)
+     * @see NumberFormat#getPercentInstance(Locale)

In DecimalFormat (String pattern, DecimalFormatSymbols symbols),

-     * <p>
-     * To obtain standard formats for a given
-     * locale, use the factory methods on NumberFormat such as
-     * getInstance or getCurrencyInstance. If you need only minor adjustments
-     * to a standard format, you can modify the format returned by
-     * a NumberFormat factory method.
      *
+     * @apiNote To obtain standard formats for a given locale, use the
+     * {@code NumberFormat} factory methods such as {@link
+     * NumberFormat#getInstance(Locale)} or {@link NumberFormat#getCurrencyInstance(Locale)}.
+     * If you need only minor adjustments to a standard format, you can modify
+     * the format returned by a NumberFormat factory method.
      * @param pattern a non-localized pattern string
      * @param symbols the set of symbols to be used
      * @throws    NullPointerException if any of the given arguments is null
      * @throws    IllegalArgumentException if the given pattern is invalid
-     * @see java.text.NumberFormat#getInstance
-     * @see java.text.NumberFormat#getNumberInstance
-     * @see java.text.NumberFormat#getCurrencyInstance
-     * @see java.text.NumberFormat#getPercentInstance
+     * @see NumberFormat#getInstance(Locale)
+     * @see NumberFormat#getNumberInstance(Locale)
+     * @see NumberFormat#getCurrencyInstance(Locale)
+     * @see NumberFormat#getPercentInstance(Locale)

In StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos),

-     * <p>
-     * This implementation uses the maximum precision permitted.
+     *
+     * @implSpec This implementation uses the maximum precision permitted.