Hi, Alex.
Here is an updated webrev:
http://cr.openjdk.java.net/~serb/8181566/webrev.03
The new CSR:
https://bugs.openjdk.java.net/browse/JDK-8185020
On 17.08.2017 9:48, Alex Menkov wrote:
Hi Sergey,
I'm fine with this ("the same" (for 2nd case) looks more clear to me,
but "identical" is also ok)
--alex
On 07/30/2017 16:07, Sergey Bylokhov wrote:
Hi, Alex.
Thank you for review!
I would like to propose and discuss other text:
If the "equals()" method is overridden to not use "==":
/**
* Indicates whether the specified object is equal to this info
object,
* returning {@code true} if the objects are equal.
*
* @param obj the reference object with which to compare
* @return {@code true} the specified object is equal to this info
* object; {@code false} otherwise
*/
public final boolean equals(Object obj) {
And two versions if the "==" from Object is used:
/**
* Indicates whether the specified object is equal to this info
object,
* returning {@code true} if the objects are identical.
*
* @param obj the reference object with which to compare
* @return {@code true} the specified object is equal to this info
* object; {@code false} otherwise
*/
public final boolean equals(Object obj) {
or:
/**
* Indicates whether the specified object is equal to this info
object,
* returning {@code true} if the objects are the same.
*
* @param obj the reference object with which to compare
* @return {@code true} the specified object is equal to this info
* object; {@code false} otherwise
*/
public final boolean equals(Object obj) {
In all versions the text in "@return " tag is short and the same. But
description have different words about the objects:
"identical"/"equal"/"the same".
ps: The text for the current fix was copied from the Integer.java
which I usually use when in doubts.
----- alexey.men...@oracle.com wrote:
MidiSystem.java:
@@ -1096,22 +1113,26 @@
return device;
}
}
}
- /* Provider class not specified or cannot be found, or
- provider class specified, and no appropriate device available or
- provider class and instance specified and instance cannot be found
or
is not appropriate */
+ /*
+ * Provider class not specified or cannot be found, or provider
class
+ * specified, and no appropriate device available or provider class
and
+ * instance specified and instance cannot be found or is not
appropriate
+ */
Old comment looks better (each "or" condition in a separate line)
- /* No default are specified, or if something is specified,
everything
- failed. */
+ /*
+ * No default are specified, or if something is specified,
everything
+ * failed.
+ */
"No default is specified" or "No defaults are specified"
AudioFileFormat.java:
- * Finalizes the equals method.
+ * Indicates whether the specified object is equal to this
file
type,
+ * returning {@code true} if the objects are the same.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if this file type is the same as the
{@code obj}
+ * argument; {@code false} otherwise
*/
@Override
public final boolean equals(final Object obj) {
The implementation checks if the objects are equal, not that the
objects
are the same
The same for AudioFormat.equals()
(Note that in most cases equals() methods of JavaSound classes just
call
super.equals(), i.e. they really test is the objects are the same)
--alex
On 07/20/2017 18:46, Sergey Bylokhov wrote:
The DRAFT version of CSR was created:
https://bugs.openjdk.java.net/browse/JDK-8185020
----- sergey.bylok...@oracle.com wrote:
The fix is updated:
http://cr.openjdk.java.net/~serb/8181566/webrev.01
I don't see the point of prettying up the docs on the un-used,
commented out constants.
Can't we just delete them ? Seems like the decision was made
years ago not to include them in the API
It could be removed, but I still consider them as kind of todo, I
hope
to check them one by one at some point.
--
Best regards, Sergey.
