JavaSound javadoc clarification

Summary

The specification for some of JavaSound API contains incorrect or incomplete sentences.

Problem

The specification for most of hashcode()/equals() and some others methods does not have correct specification.

Solution

The specifications were unified across methods in the package.

Specification

Links for convenience:

• Webrev: http://cr.openjdk.java.net/~serb/8181566/webrev.03

javax/sound/midi/MidiDevice.Info

   /**
-   * Reports whether two objects are equal. Returns {@code true} if the
-   * objects are identical.
+   * 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 this object
-   * @return {@code true} if this object is the same as the {@code obj}
-   *         argument; {@code false} otherwise
+   * @param  obj the reference object with which to compare
+   * @return {@code true} if the specified object is equal to this info
+   *         object; {@code false} otherwise
    */
    @Override
    public final boolean equals(Object obj)

   /**
-   * Finalizes the hashcode method.
+   * Returns a hash code value for this info object.
+   *
+   * @return a hash code value for this info object
    */
    @Override
    public final int hashCode()

javax/sound/midi/Sequencer.java

   /**
-   * Determines whether two objects are equal. Returns {@code true} if the
-   * objects are identical.
+   * Indicates whether the specified object is equal to this
+   * synchronization mode, returning {@code true} if the objects are the
+   * same.
    *
    * @param  obj the reference object with which to compare
-   * @return {@code true} if this object is the same as the {@code obj}
-   *         argument, {@code false} otherwise
+   * @return {@code true} if the specified object is equal to this
+   *         synchronization mode; {@code false} otherwise
    */
    @Override
    public final boolean equals(Object obj) 

   /**
-   * Finalizes the hashcode method.
+   * Returns a hash code value for this synchronization mode.
+   *
+   * @return a hash code value for this synchronization mode
    */
    @Override
    public final int hashCode()

javax/sound/sampled/AudioFileFormat.java

   /**
-   * Finalizes the equals method.
+   * Indicates whether the specified object is equal to this file type,
+   * returning {@code true} if the objects are equal.
+   *
+   * @param  obj the reference object with which to compare
+   * @return {@code true} if the specified object is equal to this file
+   *         type; {@code false} otherwise
    */
    @Override
    public final boolean equals(final Object obj) 

   /**
-   * Finalizes the hashCode method.
+   * Returns a hash code value for this file type.
+   *
+   * @return a hash code value for this file type
    */
    @Override
    public final int hashCode() 

javax/sound/sampled/AudioFormat.java

    /**
-    * Finalizes the equals method.
+    * Indicates whether the specified object is equal to this encoding,
+    * returning {@code true} if the objects are equal.
+    *
+    * @param  obj the reference object with which to compare
+    * @return {@code true} if the specified object is equal to this
+    *         encoding; {@code false} otherwise
     */
    @Override
    public final boolean equals(final Object obj)

    /**
-    * Finalizes the hashCode method.
+    * Returns a hash code value for this encoding.
+    *
+    * @return a hash code value for this encoding
     */
    @Override
    public final int hashCode()

javax/sound/sampled/Control.java

 /**
  * An instance of the {@code Type} class represents the type of the control.
- * Static instances are provided for the common types.
  */
 public static class Type {

     /**
-     * Finalizes the equals method.
+     * Indicates whether the specified object is equal to this control type,
+     * returning {@code true} if the objects are the same.
+     *
+     * @param  obj the reference object with which to compare
+     * @return {@code true} if the specified object is equal to this control
+     *         type; {@code false} otherwise
      */
     @Override
     public final boolean equals(Object obj)

     /**
-     * Finalizes the hashCode method.
+     * Returns a hash code value for this control type.
+     *
+     * @return a hash code value for this control type
      */
     @Override
     public final int hashCode()

javax/sound/sampled/LineEvent.java

     /**
      * Indicates whether the specified object is equal to this event type,
-     * returning {@code true} if the objects are identical.
+     * returning {@code true} if the objects are the same.
      *
      * @param  obj the reference object with which to compare
-     * @return {@code true} if this event type is the same as {@code obj};
-     *         {@code false} otherwise
+     * @return {@code true} if the specified object is equal to this event
+     *         type; {@code false} otherwise
      */
     @Override
     public final boolean equals(Object obj)

     /**
-     * Finalizes the hashcode method.
+     * Returns a hash code value for this event type.
+     *
+     * @return a hash code value for this event type
      */
     @Override
     public final int hashCode()

javax/sound/sampled/Mixer.java

     /**
-     * Indicates whether two info objects are equal, returning {@code true}
-     * if they are identical.
+     * 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 this info
-     *         object
+     * @param  obj the reference object with which to compare
-     * @return {@code true} if this info object is the same as the
-     *         {@code obj} argument; {@code false} otherwise
+     * @return {@code true} if the specified object is equal to this info
+     *      object; {@code false} otherwise
      */
     @Override
     public final boolean equals(Object obj) {
         return super.equals(obj);
     }

     /**
-     * Finalizes the hashcode method.
+     * Returns a hash code value for this info object.
      *
-     * @return the hashcode for this object
+     * @return a hash code value for this info object
      */
     @Override
     public final int hashCode() {
         return super.hashCode();
     }

javax/sound/sampled/Port.java

     /**
-     * Finalizes the equals method.
+     * 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} if the specified object is equal to this info
+     *         object; {@code false} otherwise
      */
     @Override
     public final boolean equals(Object obj) {
         return super.equals(obj);
     }

     /**
-     * Finalizes the hashCode method.
+     * Returns a hash code value for this info object.
+     *
+     * @return a hash code value for this info object
      */
     @Override
     public final int hashCode() {
         return super.hashCode();
     }

javax/sound/sampled/ReverbType.java

/**
  * Indicates whether the specified object is equal to this reverb type,
- * returning {@code true} if the objects are identical.
+ * returning {@code true} if the objects are the same.
  *
  * @param  obj the reference object with which to compare
- * @return {@code true} if this reverb type is the same as {@code obj};
- *         {@code false} otherwise
+ * @return {@code true} if the specified object is equal to this reverb
+ *         type; {@code false} otherwise
  */
 @Override
 public final boolean equals(Object obj) {
     return super.equals(obj);
 }

 /**
- * Finalizes the hashcode method.
+ * Returns a hash code value for this reverb type.
+ *
+ * @return a hash code value for this reverb type
  */
 @Override
 public final int hashCode() {
     return super.hashCode();
 }

javax/sound/sampled/CompoundControl

 /**
  * An instance of the {@code CompoundControl.Type} inner class identifies
- * one kind of compound control. Static instances are provided for the
- * common types.
+ * one kind of compound control.
  *
  * @author Kara Kytle
  * @since 1.3
  */
 public static class Type extends Control.Type

javax/sound/midi/SysexMessage.java

  * @param  length the length of the valid message data in the array; it
  *         should be non-negative and less than or equal to
  *         {@code data.length}
  * @throws InvalidMidiDataException if the parameter values do not specify a
- *         valid MIDI meta message
+ *         valid MIDI system exclusive message
  */
  public SysexMessage(int status, byte[] data, int length)

  * @param  length the length of the valid message data in the array,
  *         including the status byte
+ * @throws InvalidMidiDataException if the parameter values do not specify a
+ *         valid MIDI system exclusive message
  */
 @Override
 public void setMessage(byte[] data, int length) throws InvalidMidiDataException

  * @param  length the length of the valid message data in the array
  * @throws InvalidMidiDataException if the status byte is invalid for a
- *         sysex message
+ *         system exclusive message
  */
 public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException