Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8185020

JavaSound javadoc clarification

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 10
    • Component/s: client-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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:


      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              serb Sergey Bylokhov
              Reporter:
              serb Sergey Bylokhov
              Reviewed By:
              Alex Menkov
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: