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

[joe darcy]

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