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
