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

[Joseph D. Darcy]

Hi Naoto,

On 3/27/2017 4:10 PM, Naoto Sato wrote:
> 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?

I think @apiNote here is okay, it is a note more than a specification 
requirement, and it is also not inherited to the overriden methods.

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

The override can be removed as part of this changeset.

Thanks,

-Joe

>
> 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
>>