JDK 9 RFR of JDK-8177678: Overstatement of universality of Era.getDisplayName() implementation

[Naoto Sato]

Hi Joe, thank you for working on this.

- Weakening the universal wording in the parent method and inheriting 
the description in the overridden method looks fine to me. However, the 
background below mentions @implSpec, but the actual diff uses @apiNote. 
Is that what you intend?

- Should "@since 9" be kept in the override method? Which is 
contradictory to the webrev that Hamlin is working on:

http://mail.openjdk.java.net/pipermail/core-libs-dev/2017-March/046948.html

Naoto

On 3/27/17 3:53 PM, joe darcy wrote:
> Hello,
>
> Please review the patch below to fix
>
>     JDK-8177678: Overstatement of universality of Era.getDisplayName()
> implementation
>
> For background, the javadoc for Era.getDisplayName() states wishfully
> that "This default implementation is suitable for all implementations."
> Since in JDK 9 it was necessary to add an override for this method
> (JDK-8054214), the exaggerated claim of universality should be removed
> or amended.
>
> The patch weakens the statement of universality and moves it to an
> @implSpec tag. Since @implSpec tags are not inherited, the
> copy-and-paste of the documentation in the overridden method can be
> avoided.
>
> (Since this is a doc-only change, it does not have to go through the JDK
> 9 ramp down 2 approval procedures.)
>
> Thanks,
>
> -Joe
>
>
> diff -r 824789db6bea src/java.base/share/classes/java/time/chrono/Era.java
> --- a/src/java.base/share/classes/java/time/chrono/Era.java    Fri Mar
> 24 16:35:51 2017 +0000
> +++ b/src/java.base/share/classes/java/time/chrono/Era.java    Mon Mar
> 27 15:49:12 2017 -0700
> @@ -310,8 +310,8 @@
>       * The parameters control the style of the returned text and the
> locale.
>       * <p>
>       * If no textual mapping is found then the {@link #getValue()
> numeric value} is returned.
> -     * <p>
> -     * This default implementation is suitable for all implementations.
> +     *
> +     * @apiNote This default implementation is suitable for most
> implementations.
>       *
>       * @param style  the style of the text required, not null
>       * @param locale  the locale to use, not null
> diff -r 824789db6bea
> src/java.base/share/classes/java/time/chrono/JapaneseEra.java
> --- a/src/java.base/share/classes/java/time/chrono/JapaneseEra.java Fri
> Mar 24 16:35:51 2017 +0000
> +++ b/src/java.base/share/classes/java/time/chrono/JapaneseEra.java Mon
> Mar 27 15:49:12 2017 -0700
> @@ -240,18 +240,10 @@
>      }
>
>      /**
> -     * Gets the textual representation of this era.
> -     * <p>
> -     * This returns the textual name used to identify the era,
> -     * suitable for presentation to the user.
> -     * The parameters control the style of the returned text and the
> locale.
> -     * <p>
> -     * If no textual mapping is found then the {@link #getValue()
> numeric value}
> -     * is returned.
> +     * {@inheritDoc}
>       *
> -     * @param style  the style of the text required, not null
> -     * @param locale  the locale to use, not null
> -     * @return the text value of the era, not null
> +     * @param style {@inheritDoc}
> +     * @param locale {@inheritDoc}
>       * @since 9
>       */
>      @Override
>