Summary

Improve java.util.Currency docs by using @apiNote and @implNote to distinguish the specification from other wording.

Problem

In the class description, the final sentence: "It is recommended to use BigDecimal class while dealing with Currency or monetary values as it provides better handling of floating point numbers and their operations." reads as a recommendation/note, not specification.

Additionally, the methods getSymbol() and getDisplayName() have doc wording: "this is equivalent to..." which would be better worded as an implementation specific note.

Solution

Use @apiNote and @implNote where applicable.

Specification

In the class description,

- * <p>
+ * @apiNote
  * It is recommended to use {@link java.math.BigDecimal} class while dealing
  * with {@code Currency} or monetary values as it provides better handling of floating
  * point numbers and their operations.

In the doc of getSymbol(),

-     * <p>
+     *
+     * @implNote
      * This is equivalent to calling
      * {@link #getSymbol(Locale)
      *     getSymbol(Locale.getDefault(Locale.Category.DISPLAY))}.

In the doc of getDisplayName(),

-     * <p>
+     *
+     * @implNote
      * This is equivalent to calling
      * {@link #getDisplayName(Locale)
      *     getDisplayName(Locale.getDefault(Locale.Category.DISPLAY))}.