<Sound Dev> [10] Review Request: 8181566 JavaSound javadoc clarification

[Alex Menkov]

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.bylokhov at 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.
>