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

[Naoto Sato]

OK, Looks fine to me.

Naoto

On 3/27/17 4:22 PM, Joseph D. Darcy wrote:
> 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
>>>
>