changeset 47195:b309b58eb190

8181566: JavaSound javadoc clarification Reviewed-by: amenkov
author serb
date Thu, 31 Aug 2017 13:00:23 -0700
parents c045b3720b1e
children a3211bb4daff
files jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileWriter.java jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java jdk/src/java.desktop/share/classes/javax/sound/midi/spi/package-info.java jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFileFormat.java jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFormat.java jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioInputStream.java jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioPermission.java jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java jdk/src/java.desktop/share/classes/javax/sound/sampled/BooleanControl.java jdk/src/java.desktop/share/classes/javax/sound/sampled/Clip.java jdk/src/java.desktop/share/classes/javax/sound/sampled/CompoundControl.java jdk/src/java.desktop/share/classes/javax/sound/sampled/Control.java jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java jdk/src/java.desktop/share/classes/javax/sound/sampled/Line.java jdk/src/java.desktop/share/classes/javax/sound/sampled/LineEvent.java jdk/src/java.desktop/share/classes/javax/sound/sampled/LineUnavailableException.java jdk/src/java.desktop/share/classes/javax/sound/sampled/Mixer.java jdk/src/java.desktop/share/classes/javax/sound/sampled/Port.java jdk/src/java.desktop/share/classes/javax/sound/sampled/ReverbType.java jdk/src/java.desktop/share/classes/javax/sound/sampled/SourceDataLine.java jdk/src/java.desktop/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java jdk/src/java.desktop/share/classes/javax/sound/sampled/package-info.java jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/package-info.java
diffstat 45 files changed, 725 insertions(+), 573 deletions(-) [+]
line wrap: on
line diff
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,6 +39,9 @@
  */
 public class InvalidMidiDataException extends Exception {
 
+    /**
+     * Use serialVersionUID from JDK 1.3 for interoperability.
+     */
     private static final long serialVersionUID = 2780771756789932067L;
 
     /**
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,8 +54,8 @@
 
     /**
      * Status byte for {@code MetaMessage} (0xFF, or 255), which is used in MIDI
-     * files. It has the same value as SYSTEM_RESET, which is used in the
-     * real-time "MIDI wire" protocol.
+     * files. It has the same value as {@link ShortMessage#SYSTEM_RESET}, which
+     * is used in the real-time "MIDI wire" protocol.
      *
      * @see MidiMessage#getStatus
      */
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -64,11 +64,11 @@
  * {@code MidiDevice} instance, the following rules apply:
  *
  * <ul>
- * <li>After an explicit open (either before or after implicit opens), the
- * device will not be closed by implicit closing. The only way to close an
- * explicitly opened device is an explicit close.</li>
- * <li>An explicit close always closes the device, even if it also has been
- * opened implicitly. A subsequent implicit close has no further effect.</li>
+ *   <li>After an explicit open (either before or after implicit opens), the
+ *   device will not be closed by implicit closing. The only way to close an
+ *   explicitly opened device is an explicit close.
+ *   <li>An explicit close always closes the device, even if it also has been
+ *   opened implicitly. A subsequent implicit close has no further effect.
  * </ul>
  *
  * To detect if a MidiDevice represents a hardware MIDI port, the following
@@ -76,7 +76,7 @@
  *
  * <pre>{@code
  * MidiDevice device = ...;
- * if ( ! (device instanceof Sequencer) && ! (device instanceof Synthesizer)) {
+ * if (!(device instanceof Sequencer) && !(device instanceof Synthesizer)) {
  *   // we're now sure that device represents a MIDI port
  *   // ...
  * }
@@ -112,7 +112,8 @@
      * resources and allow applications to exit cleanly.
      * <p>
      * Note that some devices, once closed, cannot be reopened. Attempts to
-     * reopen such a device will always result in a MidiUnavailableException.
+     * reopen such a device will always result in a
+     * {@code MidiUnavailableException}.
      *
      * @throws MidiUnavailableException thrown if the device cannot be opened
      *         due to resource restrictions
@@ -198,7 +199,8 @@
 
     /**
      * Returns all currently active, non-closed receivers connected with this
-     * MidiDevice. A receiver can be removed from the device by closing it.
+     * {@code MidiDevice}. A receiver can be removed from the device by closing
+     * it.
      * <p>
      * Usually the returned receivers implement the {@code MidiDeviceReceiver}
      * interface.
@@ -231,7 +233,8 @@
 
     /**
      * Returns all currently active, non-closed transmitters connected with this
-     * MidiDevice. A transmitter can be removed from the device by closing it.
+     * {@code MidiDevice}. A transmitter can be removed from the device by
+     * closing it.
      * <p>
      * Usually the returned transmitters implement the
      * {@code MidiDeviceTransmitter} interface.
@@ -288,12 +291,12 @@
         }
 
         /**
-         * 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) {
@@ -301,7 +304,9 @@
         }
 
         /**
-         * 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() {
@@ -353,5 +358,5 @@
         public final String toString() {
             return name;
         }
-    } // class Info
+    }
 }
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,9 +35,11 @@
 public interface MidiDeviceReceiver extends Receiver {
 
     /**
-     * Obtains a MidiDevice object which is an owner of this Receiver.
+     * Obtains a {@code MidiDevice} object which is an owner of this
+     * {@code Receiver}.
      *
-     * @return a MidiDevice object which is an owner of this Receiver
+     * @return a {@code MidiDevice} object which is an owner of this
+     *         {@code Receiver}
      */
     MidiDevice getMidiDevice();
 }
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,9 +35,11 @@
 public interface MidiDeviceTransmitter extends Transmitter {
 
     /**
-     * Obtains a MidiDevice object which is an owner of this Transmitter.
+     * Obtains a {@code MidiDevice} object which is an owner of this
+     * {@code Transmitter}.
      *
-     * @return a MidiDevice object which is an owner of this Transmitter
+     * @return a {@code MidiDevice} object which is an owner of this
+     *         {@code Transmitter}
      */
     MidiDevice getMidiDevice();
 }
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -44,37 +44,31 @@
  * implementations:
  *
  * <table border=1>
-    <caption>MIDI File Format Properties</caption>
- *  <tr>
- *   <th>Property key</th>
- *   <th>Value type</th>
- *   <th>Description</th>
- *  </tr>
- *  <tr>
- *   <td>&quot;author&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>name of the author of this file</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;title&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>title of this file</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;copyright&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>copyright message</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;date&quot;</td>
- *   <td>{@link java.util.Date Date}</td>
- *   <td>date of the recording or release</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;comment&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>an arbitrary text</td>
- *  </tr>
+ * <caption>MIDI File Format Properties</caption>
+ *   <tr>
+ *     <th>Property key
+ *     <th>Value type
+ *     <th>Description
+ *   <tr>
+ *     <td>&quot;author&quot;
+ *     <td>{@link String String}
+ *     <td>name of the author of this file
+ *   <tr>
+ *     <td>&quot;title&quot;
+ *     <td>{@link String String}
+ *     <td>title of this file
+ *   <tr>
+ *     <td>&quot;copyright&quot;
+ *     <td>{@link String String}
+ *     <td>copyright message
+ *   <tr>
+ *     <td>&quot;date&quot;
+ *     <td>{@link java.util.Date Date}
+ *     <td>date of the recording or release
+ *   <tr>
+ *     <td>&quot;comment&quot;
+ *     <td>{@link String String}
+ *     <td>an arbitrary text
  * </table>
  *
  * @author Kara Kytle
@@ -135,10 +129,10 @@
      * @param  divisionType the timing division type (PPQ or one of the SMPTE
      *         types)
      * @param  resolution the timing resolution
-     * @param  bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if
-     *         not known
+     * @param  bytes the length of the MIDI file in bytes, or
+     *         {@link #UNKNOWN_LENGTH} if not known
      * @param  microseconds the duration of the file in microseconds, or
-     *         UNKNOWN_LENGTH if not known
+     *         {@link #UNKNOWN_LENGTH} if not known
      * @see #UNKNOWN_LENGTH
      * @see Sequence#PPQ
      * @see Sequence#SMPTE_24
@@ -163,10 +157,10 @@
      * @param  divisionType the timing division type (PPQ or one of the SMPTE
      *         types)
      * @param  resolution the timing resolution
-     * @param  bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if
-     *         not known
+     * @param  bytes the length of the MIDI file in bytes, or
+     *         {@code UNKNOWN_LENGTH} if not known
      * @param  microseconds the duration of the file in microseconds, or
-     *         UNKNOWN_LENGTH if not known
+     *         {@code UNKNOWN_LENGTH} if not known
      * @param  properties a {@code Map<String,Object>} object with properties
      * @see #UNKNOWN_LENGTH
      * @see Sequence#PPQ
@@ -224,7 +218,8 @@
     /**
      * Obtains the length of the MIDI file, expressed in 8-bit bytes.
      *
-     * @return the number of bytes in the file, or UNKNOWN_LENGTH if not known
+     * @return the number of bytes in the file, or {@code UNKNOWN_LENGTH} if not
+     *         known
      * @see #UNKNOWN_LENGTH
      */
     public int getByteLength() {
@@ -234,8 +229,8 @@
     /**
      * Obtains the length of the MIDI file, expressed in microseconds.
      *
-     * @return the file's duration in microseconds, or UNKNOWN_LENGTH if not
-     *         known
+     * @return the file's duration in microseconds, or {@code UNKNOWN_LENGTH} if
+     *         not known
      * @see Sequence#getMicrosecondLength()
      * @see #getByteLength
      * @see #UNKNOWN_LENGTH
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java	Thu Aug 31 13:00:23 2017 -0700
@@ -38,29 +38,29 @@
  * The base {@code MidiMessage} class provides access to three types of
  * information about a MIDI message:
  * <ul>
- * <li>The messages's status byte</li>
- * <li>The total length of the message in bytes (the status byte plus any data
- * bytes)</li>
- * <li>A byte array containing the complete message</li>
+ *   <li>The messages's status byte
+ *   <li>The total length of the message in bytes (the status byte plus any data
+ *   bytes)
+ *   <li>A byte array containing the complete message
  * </ul>
  *
  * {@code MidiMessage} includes methods to get, but not set, these values.
  * Setting them is a subclass responsibility.
  * <p>
- * <a id="integersVsBytes"></a> The MIDI standard expresses MIDI data in
- * bytes. However, because Java<sup>TM</sup> uses signed bytes, the Java Sound
- * API uses integers instead of bytes when expressing MIDI data. For example,
- * the {@link #getStatus()} method of {@code MidiMessage} returns MIDI status
- * bytes as integers. If you are processing MIDI data that originated outside
- * Java Sound and now is encoded as signed bytes, the bytes can be
- * converted to integers using this conversion:
+ * <a id="integersVsBytes"></a>The MIDI standard expresses MIDI data in bytes.
+ * However, because Java&trade; uses signed bytes, the Java Sound API uses
+ * integers instead of bytes when expressing MIDI data. For example, the
+ * {@link #getStatus()} method of {@code MidiMessage} returns MIDI status bytes
+ * as integers. If you are processing MIDI data that originated outside Java
+ * Sound and now is encoded as signed bytes, the bytes can be converted to
+ * integers using this conversion:
  * <p style="text-align:center">
  * {@code int i = (int)(byte & 0xFF)}
  * <p>
  * If you simply need to pass a known MIDI byte value as a method parameter, it
  * can be expressed directly as an integer, using (for example) decimal or
  * hexadecimal notation. For instance, to pass the "active sensing" status byte
- * as the first argument to ShortMessage's
+ * as the first argument to {@code ShortMessage}'s
  * {@link ShortMessage#setMessage(int) setMessage(int)} method, you can express
  * it as 254 or 0xFE.
  *
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java	Thu Aug 31 13:00:23 2017 -0700
@@ -57,7 +57,7 @@
  * one or more {@code MidiSystem} methods to learn what devices are installed
  * and to obtain the ones needed in that application.
  * <p>
- * The class also has methods for reading files, streams, and  URLs that contain
+ * The class also has methods for reading files, streams, and URLs that contain
  * standard MIDI file data or soundbanks. You can query the {@code MidiSystem}
  * for the format of a specified MIDI file.
  * <p>
@@ -77,33 +77,28 @@
  * <table class="striped">
  * <caption>MIDI System Property Keys</caption>
  * <thead>
- *  <tr>
- *   <th>Property Key</th>
- *   <th>Interface</th>
- *   <th>Affected Method</th>
- *  </tr>
+ *   <tr>
+ *     <th>Property Key
+ *     <th>Interface
+ *     <th>Affected Method
  * </thead>
  * <tbody>
- *  <tr>
- *   <td>{@code javax.sound.midi.Receiver}</td>
- *   <td>{@link Receiver}</td>
- *   <td>{@link #getReceiver}</td>
- *  </tr>
- *  <tr>
- *   <td>{@code javax.sound.midi.Sequencer}</td>
- *   <td>{@link Sequencer}</td>
- *   <td>{@link #getSequencer}</td>
- *  </tr>
- *  <tr>
- *   <td>{@code javax.sound.midi.Synthesizer}</td>
- *   <td>{@link Synthesizer}</td>
- *   <td>{@link #getSynthesizer}</td>
- *  </tr>
- *  <tr>
- *   <td>{@code javax.sound.midi.Transmitter}</td>
- *   <td>{@link Transmitter}</td>
- *   <td>{@link #getTransmitter}</td>
- *  </tr>
+ *   <tr>
+ *     <td>{@code javax.sound.midi.Receiver}
+ *     <td>{@link Receiver}
+ *     <td>{@link #getReceiver}
+ *   <tr>
+ *     <td>{@code javax.sound.midi.Sequencer}
+ *     <td>{@link Sequencer}
+ *     <td>{@link #getSequencer}
+ *   <tr>
+ *     <td>{@code javax.sound.midi.Synthesizer}
+ *     <td>{@link Synthesizer}
+ *     <td>{@link #getSynthesizer}
+ *   <tr>
+ *     <td>{@code javax.sound.midi.Transmitter}
+ *     <td>{@link Transmitter}
+ *     <td>{@link #getTransmitter}
  * </tbody>
  * </table>
  *
@@ -567,8 +562,7 @@
      * @return an {@code MidiFileFormat} object describing the MIDI file format
      * @throws InvalidMidiDataException if the stream does not point to valid
      *         MIDI file data recognized by the system
-     * @throws IOException if an I/O exception occurs while accessing the
-     *         stream
+     * @throws IOException if an I/O exception occurs while accessing the stream
      * @throws NullPointerException if {@code stream} is {@code null}
      * @see #getMidiFileFormat(URL)
      * @see #getMidiFileFormat(File)
@@ -1027,21 +1021,42 @@
     }
 
     // HELPER METHODS
+
+    /**
+     * Obtains the list of MidiDeviceProviders installed on the system.
+     *
+     * @return the list of MidiDeviceProviders installed on the system
+     */
     @SuppressWarnings("unchecked")
     private static List<MidiDeviceProvider> getMidiDeviceProviders() {
         return (List<MidiDeviceProvider>) getProviders(MidiDeviceProvider.class);
     }
 
+    /**
+     * Obtains the list of SoundbankReaders installed on the system.
+     *
+     * @return the list of SoundbankReaders installed on the system
+     */
     @SuppressWarnings("unchecked")
     private static List<SoundbankReader> getSoundbankReaders() {
         return (List<SoundbankReader>) getProviders(SoundbankReader.class);
     }
 
+    /**
+     * Obtains the list of MidiFileWriters installed on the system.
+     *
+     * @return the list of MidiFileWriters installed on the system
+     */
     @SuppressWarnings("unchecked")
     private static List<MidiFileWriter> getMidiFileWriters() {
         return (List<MidiFileWriter>) getProviders(MidiFileWriter.class);
     }
 
+    /**
+     * Obtains the list of MidiFileReaders installed on the system.
+     *
+     * @return the list of MidiFileReaders installed on the system
+     */
     @SuppressWarnings("unchecked")
     private static List<MidiFileReader> getMidiFileReaders() {
         return (List<MidiFileReader>) getProviders(MidiFileReader.class);
@@ -1056,6 +1071,7 @@
      *
      * @param  deviceClass The requested device type, one of Synthesizer.class,
      *         Sequencer.class, Receiver.class or Transmitter.class
+     * @return default MidiDevice of the specified type
      * @throws MidiUnavailableException on failure
      */
     private static MidiDevice getDefaultDeviceWrapper(Class<?> deviceClass)
@@ -1074,6 +1090,7 @@
      *
      * @param  deviceClass The requested device type, one of Synthesizer.class,
      *         Sequencer.class, Receiver.class or Transmitter.class
+     * @return default MidiDevice of the specified type.
      * @throws IllegalArgumentException on failure
      */
     private static MidiDevice getDefaultDevice(Class<?> deviceClass) {
@@ -1098,9 +1115,12 @@
             }
         }
 
-        /* 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
+         */
         if (instanceName != null) {
             device = getNamedDevice(instanceName, providers, deviceClass);
             if (device != null) {
@@ -1108,8 +1128,10 @@
             }
         }
 
-        /* No default are specified, or if something is specified, everything
-           failed. */
+        /*
+         * No defaults are specified, or if something is specified, everything
+         * failed
+         */
         device = getFirstDevice(providers, deviceClass);
         if (device != null) {
             return device;
@@ -1176,6 +1198,17 @@
      * @param  provider The MidiDeviceProvider to check for MidiDevices
      * @param  deviceClass The requested device type, one of Synthesizer.class,
      *         Sequencer.class, Receiver.class or Transmitter.class
+     * @param  allowSynthesizer if true, Synthesizers are considered
+     *         appropriate. Otherwise only pure MidiDevices are considered
+     *         appropriate (unless allowSequencer is true). This flag only has
+     *         an effect for deviceClass Receiver and Transmitter. For other
+     *         device classes (Sequencer and Synthesizer), this flag has no
+     *         effect.
+     * @param  allowSequencer if true, Sequencers are considered appropriate.
+     *         Otherwise only pure MidiDevices are considered appropriate
+     *         (unless allowSynthesizer is true). This flag only has an effect
+     *         for deviceClass Receiver and Transmitter. For other device
+     *         classes (Sequencer and Synthesizer), this flag has no effect.
      * @return A MidiDevice matching the requirements, or null if none is found
      */
     private static MidiDevice getNamedDevice(String deviceName,
@@ -1237,6 +1270,17 @@
      *         MidiDevices
      * @param  deviceClass The requested device type, one of Synthesizer.class,
      *         Sequencer.class, Receiver.class or Transmitter.class
+     * @param  allowSynthesizer if true, Synthesizers are considered
+     *         appropriate. Otherwise only pure MidiDevices are considered
+     *         appropriate (unless allowSequencer is true). This flag only has
+     *         an effect for deviceClass Receiver and Transmitter. For other
+     *         device classes (Sequencer and Synthesizer), this flag has no
+     *         effect.
+     * @param  allowSequencer if true, Sequencers are considered appropriate.
+     *         Otherwise only pure MidiDevices are considered appropriate
+     *         (unless allowSynthesizer is true). This flag only has an effect
+     *         for deviceClass Receiver and Transmitter. For other device
+     *         classes (Sequencer and Synthesizer), this flag has no effect.
      * @return A Mixer matching the requirements, or null if none is found
      */
     private static MidiDevice getNamedDevice(String deviceName,
@@ -1294,6 +1338,17 @@
      * @param  provider The MidiDeviceProvider to check for MidiDevices
      * @param  deviceClass The requested device type, one of Synthesizer.class,
      *         Sequencer.class, Receiver.class or Transmitter.class
+     * @param  allowSynthesizer if true, Synthesizers are considered
+     *         appropriate. Otherwise only pure MidiDevices are considered
+     *         appropriate (unless allowSequencer is true). This flag only has
+     *         an effect for deviceClass Receiver and Transmitter. For other
+     *         device classes (Sequencer and Synthesizer), this flag has no
+     *         effect.
+     * @param  allowSequencer if true, Sequencers are considered appropriate.
+     *         Otherwise only pure MidiDevices are considered appropriate
+     *         (unless allowSynthesizer is true). This flag only has an effect
+     *         for deviceClass Receiver and Transmitter. For other device
+     *         classes (Sequencer and Synthesizer), this flag has no effect.
      * @return A MidiDevice is considered appropriate, or null if no appropriate
      *         device is found
      */
@@ -1351,6 +1406,17 @@
      * @param  providers The List of MidiDeviceProviders to search
      * @param  deviceClass The requested device type, one of Synthesizer.class,
      *         Sequencer.class, Receiver.class or Transmitter.class
+     * @param  allowSynthesizer if true, Synthesizers are considered
+     *         appropriate. Otherwise only pure MidiDevices are considered
+     *         appropriate (unless allowSequencer is true). This flag only has
+     *         an effect for deviceClass Receiver and Transmitter. For other
+     *         device classes (Sequencer and Synthesizer), this flag has no
+     *         effect.
+     * @param  allowSequencer if true, Sequencers are considered appropriate.
+     *         Otherwise only pure MidiDevices are considered appropriate
+     *         (unless allowSynthesizer is true). This flag only has an effect
+     *         for deviceClass Receiver and Transmitter. For other device
+     *         classes (Sequencer and Synthesizer), this flag has no effect.
      * @return A MidiDevice that is considered appropriate, or null if none is
      *         found
      */
@@ -1379,6 +1445,8 @@
      * respectively.
      *
      * @param  device the MidiDevice to test
+     * @param  deviceClass The requested device type, one of Synthesizer.class,
+     *         Sequencer.class, Receiver.class or Transmitter.class
      * @param  allowSynthesizer if true, Synthesizers are considered
      *         appropriate. Otherwise only pure MidiDevices are considered
      *         appropriate (unless allowSequencer is true). This flag only has
@@ -1429,10 +1497,15 @@
      * Obtains the set of services currently installed on the system using the
      * SPI mechanism in 1.3.
      *
+     * @param  providerClass The type of providers requested. This should be one
+     *         of AudioFileReader.class, AudioFileWriter.class,
+     *         FormatConversionProvider.class, MixerProvider.class,
+     *         MidiDeviceProvider.class, MidiFileReader.class,
+     *         MidiFileWriter.class or SoundbankReader.class.
      * @return a List of instances of providers for the requested service. If no
      *         providers are available, a List of length 0 will be returned.
      */
-     private static List<?> getProviders(Class<?> providerClass) {
-         return JDK13Services.getProviders(providerClass);
+    private static List<?> getProviders(Class<?> providerClass) {
+        return JDK13Services.getProviders(providerClass);
     }
 }
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,6 +39,9 @@
  */
 public class MidiUnavailableException extends Exception {
 
+    /**
+     * Use serialVersionUID from JDK 1.3 for interoperability.
+     */
     private static final long serialVersionUID = 6093809578628944323L;
 
     /**
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -64,7 +64,7 @@
      * closed, too. For a detailed description of open/close behaviour see the
      * class description of {@link MidiDevice MidiDevice}.
      *
-     * @see javax.sound.midi.MidiSystem#getReceiver
+     * @see MidiSystem#getReceiver
      */
     @Override
     void close();
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,22 +38,22 @@
  * The {@code Sequencer} interface includes methods for the following basic MIDI
  * sequencer operations:
  * <ul>
- * <li>obtaining a sequence from MIDI file data</li>
- * <li>starting and stopping playback</li>
- * <li>moving to an arbitrary position in the sequence</li>
- * <li>changing the tempo (speed) of playback</li>
- * <li>synchronizing playback to an internal clock or to received MIDI
- * messages</li>
- * <li>controlling the timing of another device</li>
+ *   <li>obtaining a sequence from MIDI file data
+ *   <li>starting and stopping playback
+ *   <li>moving to an arbitrary position in the sequence
+ *   <li>changing the tempo (speed) of playback
+ *   <li>synchronizing playback to an internal clock or to received MIDI
+ *   messages
+ *   <li>controlling the timing of another device
  * </ul>
  * In addition, the following operations are supported, either directly, or
  * indirectly through objects that the {@code Sequencer} has access to:
  * <ul>
- * <li>editing the data by adding or deleting individual MIDI events or entire
- * tracks</li>
- * <li>muting or soloing individual tracks in the sequence</li>
- * <li>notifying listener objects about any meta-events or control-change events
- * encountered while playing back the sequence.</li>
+ *   <li>editing the data by adding or deleting individual MIDI events or entire
+ *   tracks
+ *   <li>muting or soloing individual tracks in the sequence
+ *   <li>notifying listener objects about any meta-events or control-change
+ *   events encountered while playing back the sequence
  * </ul>
  *
  * @author Kara Kytle
@@ -694,12 +694,13 @@
         }
 
         /**
-         * 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) {
@@ -708,7 +709,9 @@
         }
 
         /**
-         * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -303,9 +303,8 @@
      * @param  status the MIDI status byte
      * @param  data1 the first data byte
      * @param  data2 the second data byte
-     * @throws InvalidMidiDataException if the status byte, or all data
-     *         bytes belonging to the message, do not specify a valid MIDI
-     *         message
+     * @throws InvalidMidiDataException if the status byte, or all data bytes
+     *         belonging to the message, do not specify a valid MIDI message
      * @see #setMessage(int, int, int, int)
      * @see #setMessage(int)
      */
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,24 +31,24 @@
  * A {@code SoundbankResource} represents any audio resource stored in a
  * {@link Soundbank}. Common soundbank resources include:
  * <ul>
- * <li>Instruments. An instrument may be specified in a variety of ways.
- * However, all soundbanks have some mechanism for defining instruments. In
- * doing so, they may reference other resources stored in the soundbank. Each
- * instrument has a {@code Patch} which specifies the MIDI program and bank by
- * which it may be referenced in MIDI messages. Instrument information may be
- * stored in {@link Instrument} objects.</li>
- * <li>Audio samples. A sample typically is a sampled audio waveform which
- * contains a short sound recording whose duration is a fraction of a second, or
- * at most a few seconds. These audio samples may be used by a
- * {@link Synthesizer} to synthesize sound in response to MIDI commands, or
- * extracted for use by an application. (The terminology reflects musicians' use
- * of the word "sample" to refer collectively to a series of contiguous audio
- * samples or frames, rather than to a single, instantaneous sample.) The data
- * class for an audio sample will be an object that encapsulates the audio
- * sample data itself and information about how to interpret it (the format of
- * the audio data), such as an {@link AudioInputStream}.</li>
- * <li>Embedded sequences. A sound bank may contain built-in song data stored in
- * a data object such as a {@link Sequence}.</li>
+ *   <li>Instruments. An instrument may be specified in a variety of ways.
+ *   However, all soundbanks have some mechanism for defining instruments. In
+ *   doing so, they may reference other resources stored in the soundbank.
+ *   Each instrument has a {@code Patch} which specifies the MIDI program and
+ *   bank by which it may be referenced in MIDI messages. Instrument information
+ *   may be stored in {@link Instrument} objects.
+ *   <li>Audio samples. A sample typically is a sampled audio waveform which
+ *   contains a short sound recording whose duration is a fraction of a
+ *   second, or at most a few seconds. These audio samples may be used by a
+ *   {@link Synthesizer} to synthesize sound in response to MIDI commands, or
+ *   extracted for use by an application. (The terminology reflects musicians'
+ *   use of the word "sample" to refer collectively to a series of contiguous
+ *   audio samples or frames, rather than to a single, instantaneous sample.)
+ *   The data class for an audio sample will be an object that encapsulates
+ *   the audio sample data itself and information about how to interpret it
+ *   (the format of the audio data), such as an {@link AudioInputStream}.
+ *   <li>Embedded sequences. A sound bank may contain built-in song data stored
+ *   in a data object such as a {@link Sequence}.
  * </ul>
  * Synthesizers that use wavetable synthesis or related techniques play back the
  * audio in a sample when synthesizing notes, often when emulating the
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -49,8 +49,8 @@
  * be used by every synthesizer, even if the synthesis technique is compatible.
  * To see whether the instruments from a certain soundbank can be played by a
  * given synthesizer, invoke the
- * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported}
- * method of {@code Synthesizer}.
+ * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of
+ * {@code Synthesizer}.
  * <p>
  * "Loading" an instrument means that that instrument becomes available for
  * synthesizing notes. The instrument is loaded into the bank and program
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -40,8 +40,8 @@
  * As dictated by the Standard MIDI Files specification, two status byte values
  * are legal for a {@code SysexMessage} read from a MIDI file:
  * <ul>
- * <li>0xF0: System Exclusive message (same as in MIDI wire protocol)</li>
- * <li>0xF7: Special System Exclusive message</li>
+ *   <li>0xF0: System Exclusive message (same as in MIDI wire protocol)
+ *   <li>0xF7: Special System Exclusive message
  * </ul>
  * When Java Sound is used to handle system exclusive data that is being
  * received using MIDI wire protocol, it should place the data in one or more
@@ -49,8 +49,8 @@
  * is not known in advance; the end of the system exclusive data is marked by an
  * end-of-exclusive flag (0xF7) in the MIDI wire byte stream.
  * <ul>
- * <li>0xF0: System Exclusive message (same as in MIDI wire protocol)</li>
- * <li>0xF7: End of Exclusive (EOX)</li>
+ *   <li>0xF0: System Exclusive message (same as in MIDI wire protocol)
+ *   <li>0xF7: End of Exclusive (EOX)
  * </ul>
  * The first {@code SysexMessage} object containing data for a particular system
  * exclusive message should have the status value 0xF0. If this message contains
@@ -148,7 +148,7 @@
      *         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
      * @see #setMessage(byte[], int)
      * @see #setMessage(int, byte[], int)
      * @see #getData()
@@ -178,6 +178,8 @@
      * @param  data the system exclusive message data
      * @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 {
@@ -195,7 +197,7 @@
      * @param  data the system exclusive message data
      * @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 {
         if ( (status != 0xF0) && (status != 0xF7) ) {
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -64,10 +64,14 @@
 
     // TODO: use arrays for faster access
 
-    // the list containing the events
+    /**
+     * The list containing the events.
+     */
     private final ArrayList<MidiEvent> eventsList = new ArrayList<>();
 
-    // use a hashset to detect duplicate events in add(MidiEvent)
+    /**
+     * Use a hashset to detect duplicate events in add(MidiEvent).
+     */
     private final HashSet<MidiEvent> set = new HashSet<>();
 
     private final MidiEvent eotEvent;
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -67,7 +67,7 @@
      * open/close behaviour see the class description of
      * {@link MidiDevice MidiDevice}.
      *
-     * @see javax.sound.midi.MidiSystem#getTransmitter
+     * @see MidiSystem#getTransmitter
      */
     @Override
     void close();
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java	Thu Aug 31 13:00:23 2017 -0700
@@ -51,8 +51,8 @@
  * given type of {@code Synthesizer} always has a fixed number of voices, equal
  * to the maximum number of simultaneous notes it is capable of sounding.
  * <p>
- * <a id="description_of_active"></a> If the voice is not currently processing
- * a MIDI note, it is considered inactive. A voice is inactive when it has been
+ * <a id="description_of_active"></a>If the voice is not currently processing a
+ * MIDI note, it is considered inactive. A voice is inactive when it has been
  * given no note-on commands, or when every note-on command received has been
  * terminated by a corresponding note-off (or by an "all notes off" message).
  * For example, this happens when a synthesizer capable of playing 16
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java	Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
  * <h2>Related Documentation</h2>
  * For more information on using Java Sound see:
  * <ul>
- *     <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- *     The Java Sound Tutorial</a></li>
+ *   <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ *   The Java Sound Tutorial</a>
  * </ul>
  *
  * @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,8 +54,8 @@
      * stream's read pointer to its original position. If the input stream does
      * not support this, this method may fail with an {@code IOException}.
      *
-     * @param  stream the input stream from which file format information
-     *         should be extracted
+     * @param  stream the input stream from which file format information should
+     *         be extracted
      * @return a {@code MidiFileFormat} object describing the MIDI file format
      * @throws InvalidMidiDataException if the stream does not point to valid
      *         MIDI file data recognized by the system
@@ -68,14 +68,14 @@
             throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains the MIDI file format of the URL provided. The URL must point to
-     * valid MIDI file data.
+     * Obtains the MIDI file format of the {@code URL} provided. The {@code URL}
+     * must point to valid MIDI file data.
      *
-     * @param  url the URL from which file format information should be
+     * @param  url the {@code URL} from which file format information should be
      *         extracted
      * @return a {@code MidiFileFormat} object describing the MIDI file format
-     * @throws InvalidMidiDataException if the URL does not point to valid MIDI
-     *         file data recognized by the system
+     * @throws InvalidMidiDataException if the {@code URL} does not point to
+     *         valid MIDI file data recognized by the system
      * @throws IOException if an I/O exception occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
@@ -104,10 +104,10 @@
      * it. These parsers must be able to mark the stream, read enough data to
      * determine whether they support the stream, and, if not, reset the
      * stream's read pointer to its original position. If the input stream does
-     * not support this, this method may fail with an IOException.
+     * not support this, this method may fail with an {@code IOException}.
      *
-     * @param  stream the input stream from which the {@code Sequence} should
-     *         be constructed
+     * @param  stream the input stream from which the {@code Sequence} should be
+     *         constructed
      * @return a {@code Sequence} object based on the MIDI file data contained
      *         in the input stream
      * @throws InvalidMidiDataException if the stream does not point to valid
@@ -121,14 +121,15 @@
             throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains a MIDI sequence from the URL provided. The URL must point to
-     * valid MIDI file data.
+     * Obtains a MIDI sequence from the {@code URL} provided. The {@code URL}
+     * must point to valid MIDI file data.
      *
-     * @param  url the URL for which the {@code Sequence} should be constructed
+     * @param  url the {@code URL} for which the {@code Sequence} should be
+     *         constructed
      * @return a {@code Sequence} object based on the MIDI file data pointed to
-     *         by the URL
-     * @throws InvalidMidiDataException if the URL does not point to valid MIDI
-     *         file data recognized by the system
+     *         by the {@code URL}
+     * @throws InvalidMidiDataException if the {@code URL} does not point to
+     *         valid MIDI file data recognized by the system
      * @throws IOException if an I/O exception occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileWriter.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileWriter.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,8 +54,7 @@
      * Obtains the file types that this file writer can write from the sequence
      * specified.
      *
-     * @param  sequence the sequence for which MIDI file type support is
-     *         queried
+     * @param  sequence the sequence for which MIDI file type support is queried
      * @return array of file types. If no file types are supported, returns an
      *         array of length 0.
      * @throws NullPointerException if {@code sequence} is {@code null}
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,18 +39,18 @@
  * subclasses of {@code SoundbankReader} parse a given soundbank file, producing
  * a {@link Soundbank} object that can be loaded into a {@link Synthesizer}.
  *
+ * @author Kara Kytle
  * @since 1.3
- * @author Kara Kytle
  */
 public abstract class SoundbankReader {
 
     /**
-     * Obtains a soundbank object from the URL provided.
+     * Obtains a soundbank object from the {@code URL} provided.
      *
-     * @param  url URL representing the soundbank
+     * @param  url {@code URL} representing the soundbank
      * @return soundbank object
-     * @throws InvalidMidiDataException if the URL does not point to valid MIDI
-     *         soundbank data recognized by this soundbank reader
+     * @throws InvalidMidiDataException if the {@code URL} does not point to
+     *         valid MIDI soundbank data recognized by this soundbank reader
      * @throws IOException if an I/O error occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/package-info.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/package-info.java	Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
  * <h2>Related Documentation</h2>
  * For more information on using Java Sound see:
  * <ul>
- *     <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- *     The Java Sound Tutorial</a></li>
+ *   <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ *   The Java Sound Tutorial</a>
  * </ul>
  *
  * @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFileFormat.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFileFormat.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -51,45 +51,37 @@
  * implementations:
  *
  * <table border=1>
- *  <caption>Audio File Format Properties</caption>
- *  <tr>
- *   <th>Property key</th>
- *   <th>Value type</th>
- *   <th>Description</th>
- *  </tr>
- *  <tr>
- *   <td>&quot;duration&quot;</td>
- *   <td>{@link java.lang.Long Long}</td>
- *   <td>playback duration of the file in microseconds</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;author&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>name of the author of this file</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;title&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>title of this file</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;copyright&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>copyright message</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;date&quot;</td>
- *   <td>{@link java.util.Date Date}</td>
- *   <td>date of the recording or release</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;comment&quot;</td>
- *   <td>{@link java.lang.String String}</td>
- *   <td>an arbitrary text</td>
- *  </tr>
+ * <caption>Audio File Format Properties</caption>
+ *   <tr>
+ *     <th>Property key
+ *     <th>Value type
+ *     <th>Description
+ *   <tr>
+ *     <td>&quot;duration&quot;
+ *     <td>{@link Long Long}
+ *     <td>playback duration of the file in microseconds
+ *   <tr>
+ *     <td>&quot;author&quot;
+ *     <td>{@link String String}
+ *     <td>name of the author of this file
+ *   <tr>
+ *     <td>&quot;title&quot;
+ *     <td>{@link String String}
+ *     <td>title of this file
+ *   <tr>
+ *     <td>&quot;copyright&quot;
+ *     <td>{@link String String}
+ *     <td>copyright message
+ *   <tr>
+ *     <td>&quot;date&quot;
+ *     <td>{@link java.util.Date Date}
+ *     <td>date of the recording or release
+ *   <tr>
+ *     <td>&quot;comment&quot;
+ *     <td>{@link String String}
+ *     <td>an arbitrary text
  * </table>
  *
- *
  * @author David Rivas
  * @author Kara Kytle
  * @author Florian Bomers
@@ -351,7 +343,12 @@
         }
 
         /**
-         * 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) {
@@ -365,7 +362,9 @@
         }
 
         /**
-         * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFormat.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFormat.java	Thu Aug 31 13:00:23 2017 -0700
@@ -40,6 +40,7 @@
  * data line expects to receive for output. For a target (capture) data line,
  * the audio format specifies the kind of the data that can be read from the
  * line.
+ * <p>
  * Sound files also have audio formats, of course. The {@link AudioFileFormat}
  * class encapsulates an {@code AudioFormat} in addition to other, file-specific
  * information. Similarly, an {@link AudioInputStream} has an
@@ -92,29 +93,24 @@
  * <table class="striped">
  * <caption>Audio Format Properties</caption>
  * <thead>
- *  <tr>
- *   <th>Property key</th>
- *   <th>Value type</th>
- *   <th>Description</th>
- *  </tr>
+ *   <tr>
+ *     <th>Property key
+ *     <th>Value type
+ *     <th>Description
  * </thead>
  * <tbody>
- *  <tr>
- *   <td>&quot;bitrate&quot;</td>
- *   <td>{@link java.lang.Integer Integer}</td>
- *   <td>average bit rate in bits per second</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;vbr&quot;</td>
- *   <td>{@link java.lang.Boolean Boolean}</td>
- *   <td>{@code true}, if the file is encoded in variable bit
- *       rate (VBR)</td>
- *  </tr>
- *  <tr>
- *   <td>&quot;quality&quot;</td>
- *   <td>{@link java.lang.Integer Integer}</td>
- *   <td>encoding/conversion quality, 1..100</td>
- *  </tr>
+ *   <tr>
+ *     <td>&quot;bitrate&quot;
+ *     <td>{@link java.lang.Integer Integer}
+ *     <td>average bit rate in bits per second
+ *   <tr>
+ *     <td>&quot;vbr&quot;
+ *     <td>{@link java.lang.Boolean Boolean}
+ *     <td>{@code true}, if the file is encoded in variable bit rate (VBR)
+ *   <tr>
+ *     <td>&quot;quality&quot;
+ *     <td>{@link java.lang.Integer Integer}
+ *     <td>encoding/conversion quality, 1..100
  * </tbody>
  * </table>
  * <p>
@@ -183,8 +179,8 @@
      * @param  encoding the audio encoding technique
      * @param  sampleRate the number of samples per second
      * @param  sampleSizeInBits the number of bits in each sample
-     * @param  channels the number of channels (1 for mono, 2 for stereo,
-     *         and so on)
+     * @param  channels the number of channels (1 for mono, 2 for stereo, and so
+     *         on)
      * @param  frameSize the number of bytes in each frame
      * @param  frameRate the number of frames per second
      * @param  bigEndian indicates whether the data for a single sample is
@@ -217,7 +213,8 @@
      * @param  frameSize the number of bytes in each frame
      * @param  frameRate the number of frames per second
      * @param  bigEndian indicates whether the data for a single sample is
-     *         stored in big-endian byte order ({@code false} means little-endian)
+     *         stored in big-endian byte order ({@code false} means
+     *         little-endian)
      * @param  properties a {@code Map<String, Object>} object containing format
      *         properties
      * @since 1.5
@@ -276,9 +273,10 @@
 
     /**
      * Obtains the sample rate. For compressed formats, the return value is the
-     * sample rate of the uncompressed audio data. When this AudioFormat is used
-     * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
-     * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
+     * sample rate of the uncompressed audio data. When this {@code AudioFormat}
+     * is used for queries (e.g.
+     * {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g.
      * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample rate
      * of {@code AudioSystem.NOT_SPECIFIED} means that any sample rate is
      * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
@@ -296,10 +294,10 @@
 
     /**
      * Obtains the size of a sample. For compressed formats, the return value is
-     * the sample size of the uncompressed audio data. When this AudioFormat is
-     * used for queries (e.g. {@link AudioSystem#isConversionSupported(
-     * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
-     * capabilities (e.g.
+     * the sample size of the uncompressed audio data. When this
+     * {@code AudioFormat} is used for queries (e.g.
+     * {@link AudioSystem#isConversionSupported(AudioFormat,AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g.
      * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample size
      * of {@code AudioSystem.NOT_SPECIFIED} means that any sample size is
      * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
@@ -316,9 +314,9 @@
     }
 
     /**
-     * Obtains the number of channels. When this AudioFormat is used for queries
-     * (e.g. {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
-     * AudioSystem.isConversionSupported}) or capabilities (e.g.
+     * Obtains the number of channels. When this {@code AudioFormat} is used for
+     * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
+     * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
      * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a return
      * value of {@code AudioSystem.NOT_SPECIFIED} means that any (positive)
      * number of channels is acceptable.
@@ -333,8 +331,8 @@
     }
 
     /**
-     * Obtains the frame size in bytes. When this AudioFormat is used for
-     * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
+     * Obtains the frame size in bytes. When this {@code AudioFormat} is used
+     * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
      * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
      * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame size
      * of {@code AudioSystem.NOT_SPECIFIED} means that any frame size is
@@ -352,10 +350,10 @@
     }
 
     /**
-     * Obtains the frame rate in frames per second. When this AudioFormat is
-     * used for queries (e.g. {@link AudioSystem#isConversionSupported(
-     * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
-     * capabilities (e.g.
+     * Obtains the frame rate in frames per second. When this
+     * {@code AudioFormat} is used for queries (e.g.
+     * {@link AudioSystem#isConversionSupported(AudioFormat,AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g.
      * {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame rate
      * of {@code AudioSystem.NOT_SPECIFIED} means that any frame rate is
      * acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
@@ -551,9 +549,10 @@
      * the sound amplitude that are often used for recording speech.
      * <p>
      * You can use a predefined encoding by referring to one of the static
-     * objects created by this class, such as PCM_SIGNED or PCM_UNSIGNED.
-     * Service providers can create new encodings, such as compressed audio
-     * formats, and make these available through the {@link AudioSystem} class.
+     * objects created by this class, such as {@code PCM_SIGNED} or
+     * {@code PCM_UNSIGNED}. Service providers can create new encodings, such as
+     * compressed audio formats, and make these available through the
+     * {@link AudioSystem} class.
      * <p>
      * The {@code Encoding} class is static, so that all {@code AudioFormat}
      * objects that have the same encoding will refer to the same object (rather
@@ -609,7 +608,12 @@
         }
 
         /**
-         * 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) {
@@ -623,7 +627,9 @@
         }
 
         /**
-         * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioInputStream.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioInputStream.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -28,7 +28,6 @@
 import java.io.IOException;
 import java.io.InputStream;
 
-
 /**
  * An audio input stream is an input stream with a specified audio format and
  * length. The length is expressed in sample frames, not bytes. Several methods
@@ -42,9 +41,10 @@
  * The {@code AudioSystem} class includes many methods that manipulate
  * {@code AudioInputStream} objects. For example, the methods let you:
  * <ul>
- * <li> obtain an audio input stream from an external audio file, stream, or URL
- * <li> write an external file from an audio input stream
- * <li> convert an audio input stream to a different audio format
+ *   <li>obtain an audio input stream from an external audio file, stream, or
+ *   {@code URL}
+ *   <li>write an external file from an audio input stream
+ *   <li>convert an audio input stream to a different audio format
  * </ul>
  *
  * @author David Rivas
@@ -139,7 +139,7 @@
     /**
      * Constructs an audio input stream that reads its data from the target data
      * line indicated. The format of the stream is the same as that of the
-     * target data line, and the length is AudioSystem#NOT_SPECIFIED.
+     * target data line, and the length is {@code AudioSystem#NOT_SPECIFIED}.
      *
      * @param  line the target data line from which this stream obtains its data
      * @see AudioSystem#NOT_SPECIFIED
@@ -370,11 +370,11 @@
 
     /**
      * Returns the maximum number of bytes that can be read (or skipped over)
-     * from this audio input stream without blocking. This limit applies only
-     * to the next invocation of a {@code read} or {@code skip} method for this
+     * from this audio input stream without blocking. This limit applies only to
+     * the next invocation of a {@code read} or {@code skip} method for this
      * audio input stream; the limit can vary each time these methods are
-     * invoked. Depending on the underlying stream, an IOException may be thrown
-     * if this stream is closed.
+     * invoked. Depending on the underlying stream, an {@code IOException} may
+     * be thrown if this stream is closed.
      *
      * @return the number of bytes that can be read from this audio input stream
      *         without blocking
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioPermission.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioPermission.java	Thu Aug 31 13:00:23 2017 -0700
@@ -45,34 +45,30 @@
  * <caption>Permission target name, what the permission allows, and associated
  * risks</caption>
  * <thead>
- * <tr>
- * <th>Permission Target Name</th>
- * <th>What the Permission Allows</th>
- * <th>Risks of Allowing this Permission</th>
- * </tr>
+ *   <tr>
+ *     <th>Permission Target Name
+ *     <th>What the Permission Allows
+ *     <th>Risks of Allowing this Permission
  * </thead>
  * <tbody>
- * <tr>
- * <td>play</td>
- * <td>Audio playback through the audio device or devices on the system.
- * Allows the application to obtain and manipulate lines and mixers for
- * audio playback (rendering).</td>
- * <td>In some cases use of this permission may affect other
- * applications because the audio from one line may be mixed with other audio
- * being played on the system, or because manipulation of a mixer affects the
- * audio for all lines using that mixer.</td>
- * </tr>
- *
- * <tr>
- * <td>record</td>
- * <td>Audio recording through the audio device or devices on the system.
- * Allows the application to obtain and manipulate lines and mixers for
- * audio recording (capture).</td>
- * <td>In some cases use of this permission may affect other
- * applications because manipulation of a mixer affects the audio for all lines
- * using that mixer.
- * This permission can enable an applet or application to eavesdrop on a user.</td>
- * </tr>
+ *   <tr>
+ *     <td>play
+ *     <td>Audio playback through the audio device or devices on the system.
+ *     Allows the application to obtain and manipulate lines and mixers for
+ *     audio playback (rendering).
+ *     <td>In some cases use of this permission may affect other
+ *     applications because the audio from one line may be mixed with other
+ *     audio being played on the system, or because manipulation of a mixer
+ *     affects the audio for all lines using that mixer.
+ *   <tr>
+ *     <td>record
+ *     <td>Audio recording through the audio device or devices on the system.
+ *     Allows the application to obtain and manipulate lines and mixers for
+ *     audio recording (capture).
+ *     <td>In some cases use of this permission may affect other applications
+ *     because manipulation of a mixer affects the audio for all lines using
+ *     that mixer. This permission can enable an applet or application to
+ *     eavesdrop on a user.
  * </tbody>
  * </table>
  *
@@ -81,6 +77,9 @@
  */
 public class AudioPermission extends BasicPermission {
 
+    /**
+     * Use serialVersionUID from JDK 1.3 for interoperability.
+     */
     private static final long serialVersionUID = -5518053473477801126L;
 
     /**
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java	Thu Aug 31 13:00:23 2017 -0700
@@ -25,7 +25,6 @@
 
 package javax.sound.sampled;
 
-import java.io.EOFException;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
@@ -75,33 +74,28 @@
  * <table class="striped">
  * <caption>Audio System Property Keys</caption>
  * <thead>
- *  <tr>
- *   <th>Property Key</th>
- *   <th>Interface</th>
- *   <th>Affected Method(s)</th>
- *  </tr>
+ *   <tr>
+ *     <th>Property Key
+ *     <th>Interface
+ *     <th>Affected Method(s)
  * </thead>
  * <tbody>
- *  <tr>
- *   <td>{@code javax.sound.sampled.Clip}</td>
- *   <td>{@link Clip}</td>
- *   <td>{@link #getLine}, {@link #getClip}</td>
- *  </tr>
- *  <tr>
- *   <td>{@code javax.sound.sampled.Port}</td>
- *   <td>{@link Port}</td>
- *   <td>{@link #getLine}</td>
- *  </tr>
- *  <tr>
- *   <td>{@code javax.sound.sampled.SourceDataLine}</td>
- *   <td>{@link SourceDataLine}</td>
- *   <td>{@link #getLine}, {@link #getSourceDataLine}</td>
- *  </tr>
- *  <tr>
- *   <td>{@code javax.sound.sampled.TargetDataLine}</td>
- *   <td>{@link TargetDataLine}</td>
- *   <td>{@link #getLine}, {@link #getTargetDataLine}</td>
- *  </tr>
+ *   <tr>
+ *     <td>{@code javax.sound.sampled.Clip}
+ *     <td>{@link Clip}
+ *     <td>{@link #getLine}, {@link #getClip}
+ *   <tr>
+ *     <td>{@code javax.sound.sampled.Port}
+ *     <td>{@link Port}
+ *     <td>{@link #getLine}
+ *   <tr>
+ *     <td>{@code javax.sound.sampled.SourceDataLine}
+ *     <td>{@link SourceDataLine}
+ *     <td>{@link #getLine}, {@link #getSourceDataLine}
+ *   <tr>
+ *     <td>{@code javax.sound.sampled.TargetDataLine}
+ *     <td>{@link TargetDataLine}
+ *     <td>{@link #getLine}, {@link #getTargetDataLine}
  * </tbody>
  * </table>
  *
@@ -125,20 +119,19 @@
  * matching {@code Mixer.Info} object is found, or the mixer name is not
  * specified, the first mixer from the resulting list, which provides the
  * respective line interface, will be returned.
- *
+ * <p>
  * For example, the property {@code javax.sound.sampled.Clip} with a value
- * {@code "com.sun.media.sound.MixerProvider#SunClip"}
- * will have the following consequences when {@code getLine} is called
- * requesting a {@code Clip} instance: if the class
- * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
- * mixer providers, the first {@code Clip} from the first mixer with name
- * {@code "SunClip"} will be returned. If it cannot be found, the
- * first {@code Clip} from the first mixer of the specified provider will be
+ * {@code "com.sun.media.sound.MixerProvider#SunClip"} will have the following
+ * consequences when {@code getLine} is called requesting a {@code Clip}
+ * instance: if the class {@code com.sun.media.sound.MixerProvider} exists in
+ * the list of installed mixer providers, the first {@code Clip} from the first
+ * mixer with name {@code "SunClip"} will be returned. If it cannot be found,
+ * the first {@code Clip} from the first mixer of the specified provider will be
  * returned, regardless of name. If there is none, the first {@code Clip} from
- * the first {@code Mixer} with name {@code "SunClip"} in the list of
- * all mixers (as returned by {@code getMixerInfo}) will be returned, or, if not
- * found, the first {@code Clip} of the first {@code Mixer} that can be found in
- * the list of all mixers is returned. If that fails, too, an
+ * the first {@code Mixer} with name {@code "SunClip"} in the list of all mixers
+ * (as returned by {@code getMixerInfo}) will be returned, or, if not found, the
+ * first {@code Clip} of the first {@code Mixer} that can be found in the list
+ * of all mixers is returned. If that fails, too, an
  * {@code IllegalArgumentException} is thrown.
  *
  * @author Kara Kytle
@@ -479,7 +472,6 @@
      * @param  mixerInfo a {@code Mixer.Info} object representing the desired
      *         mixer, or {@code null} for the system default mixer
      * @return a clip object from the specified mixer
-     *
      * @throws LineUnavailableException if a clip is not available from this
      *         mixer due to resource restrictions
      * @throws SecurityException if a clip is not available from this mixer due
@@ -670,9 +662,9 @@
      *
      * @param  sourceEncoding the encoding for which conversion support is
      *         queried
-     * @return array of encodings. If {@code sourceEncoding}is not supported, an
-     *         array of length 0 is returned. Otherwise, the array will have a
-     *         length of at least 1, representing {@code sourceEncoding}
+     * @return array of encodings. If {@code sourceEncoding} is not supported,
+     *         an array of length 0 is returned. Otherwise, the array will have
+     *         a length of at least 1, representing {@code sourceEncoding}
      *         (no conversion).
      * @throws NullPointerException if {@code sourceEncoding} is {@code null}
      */
@@ -935,15 +927,15 @@
     }
 
     /**
-     * Obtains the audio file format of the specified URL. The URL must point to
-     * valid audio file data.
+     * Obtains the audio file format of the specified {@code URL}. The
+     * {@code URL} must point to valid audio file data.
      *
-     * @param  url the URL from which file format information should be
+     * @param  url the {@code URL} from which file format information should be
      *         extracted
      * @return an {@code AudioFileFormat} object describing the audio file
      *         format
-     * @throws UnsupportedAudioFileException if the URL does not point to valid
-     *         audio file data recognized by the system
+     * @throws UnsupportedAudioFileException if the {@code URL} does not point
+     *         to valid audio file data recognized by the system
      * @throws IOException if an input/output exception occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
@@ -1021,15 +1013,15 @@
     }
 
     /**
-     * Obtains an audio input stream from the URL provided. The URL must point
-     * to valid audio file data.
+     * Obtains an audio input stream from the {@code URL} provided. The
+     * {@code URL} must point to valid audio file data.
      *
-     * @param  url the URL for which the {@code AudioInputStream} should be
-     *         constructed
+     * @param  url the {@code URL} for which the {@code AudioInputStream} should
+     *         be constructed
      * @return an {@code AudioInputStream} object based on the audio file data
-     *         pointed to by the URL
-     * @throws UnsupportedAudioFileException if the URL does not point to valid
-     *         audio file data recognized by the system
+     *         pointed to by the {@code URL}
+     * @throws UnsupportedAudioFileException if the {@code URL} does not point
+     *         to valid audio file data recognized by the system
      * @throws IOException if an I/O exception occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
@@ -1121,8 +1113,8 @@
      * Obtains the file types that the system can write from the audio input
      * stream specified.
      *
-     * @param  stream the audio input stream for which audio file type
-     *         support is queried
+     * @param  stream the audio input stream for which audio file type support
+     *         is queried
      * @return array of file types. If no file types are supported, an array of
      *         length 0 is returned.
      * @throws NullPointerException if {@code stream} is {@code null}
@@ -1175,8 +1167,8 @@
      * type to the output stream provided. Some file types require that the
      * length be written into the file header; such files cannot be written from
      * start to finish unless the length is known in advance. An attempt to
-     * write a file of such a type will fail with an IOException if the length
-     * in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
+     * write a file of such a type will fail with an {@code IOException} if the
+     * length in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
      *
      * @param  stream the audio input stream containing audio data to be written
      *         to the file
@@ -1250,7 +1242,9 @@
     // METHODS FOR INTERNAL IMPLEMENTATION USE
 
     /**
-     * Obtains the set of MixerProviders on the system.
+     * Obtains the list of MixerProviders currently installed on the system.
+     *
+     * @return the list of MixerProviders currently installed on the system
      */
     @SuppressWarnings("unchecked")
     private static List<MixerProvider> getMixerProviders() {
@@ -1331,9 +1325,12 @@
             }
         }
 
-        /* Provider class not specified or
-           provider class cannot be found, or
-           provider class and instance specified and instance cannot be found or is not appropriate */
+        /*
+         *  - Provider class not specified, or
+         *  - provider class cannot be found, or
+         *  - provider class and instance specified and instance cannot be found
+         *    or is not appropriate
+         */
         if (instanceName != null) {
             mixer = getNamedMixer(instanceName, providers, info);
             if (mixer != null) {
@@ -1342,8 +1339,10 @@
         }
 
 
-        /* No default are specified, or if something is specified, everything
-           failed. */
+        /*
+         * No defaults are specified, or if something is specified, everything
+         * failed
+         */
         return null;
     }
 
@@ -1436,10 +1435,14 @@
 
     /**
      * Checks if a Mixer is appropriate. A Mixer is considered appropriate if it
-     * support the given line type. If isMixingRequired is true and the line
-     * type is an output one (SourceDataLine, Clip), the mixer is appropriate if
-     * it supports at least 2 (concurrent) lines of the given type.
+     * support the given line type. If isMixingRequired is {@code true} and the
+     * line type is an output one (SourceDataLine, Clip), the mixer is
+     * appropriate if it supports at least 2 (concurrent) lines of the given
+     * type.
      *
+     * @param  mixer The mixer to check
+     * @param  lineInfo The line to check
+     * @param  isMixingRequired Is the mixing required or not
      * @return {@code true} if the mixer is considered appropriate according to
      *         the rules given above, {@code false} otherwise
      */
@@ -1461,6 +1464,10 @@
 
     /**
      * Like getMixerInfo, but return List.
+     *
+     * @return a List of info objects for the currently installed mixers. If no
+     *         mixers are available on the system, an empty List is returned.
+     * @see #getMixerInfo()
      */
     private static List<Mixer.Info> getMixerInfoList() {
         List<MixerProvider> providers = getMixerProviders();
@@ -1469,6 +1476,11 @@
 
     /**
      * Like getMixerInfo, but return List.
+     *
+     * @param  providers The list of MixerProviders
+     * @return a List of info objects for the currently installed mixers. If no
+     *         mixers are available on the system, an empty List is returned.
+     * @see #getMixerInfo()
      */
     private static List<Mixer.Info> getMixerInfoList(List<MixerProvider> providers) {
         List<Mixer.Info> infos = new ArrayList<>();
@@ -1491,6 +1503,11 @@
      * Obtains the set of services currently installed on the system using the
      * SPI mechanism in 1.3.
      *
+     * @param  providerClass The type of providers requested. This should be one
+     *         of AudioFileReader.class, AudioFileWriter.class,
+     *         FormatConversionProvider.class, MixerProvider.class,
+     *         MidiDeviceProvider.class, MidiFileReader.class,
+     *         MidiFileWriter.class or SoundbankReader.class.
      * @return a List of instances of providers for the requested service. If no
      *         providers are available, a vector of length 0 will be returned.
      */
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/BooleanControl.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/BooleanControl.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -121,7 +121,7 @@
     /**
      * Provides a string representation of the control.
      *
-     * @return a string description
+     * @return a string representation of the control
      */
     @Override
     public String toString() {
@@ -153,7 +153,7 @@
         /**
          * Constructs a new boolean control type.
          *
-         * @param name the name of the new boolean control type
+         * @param  name the name of the new boolean control type
          */
         protected Type(final String name) {
             super(name);
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Clip.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Clip.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -178,13 +178,13 @@
     /**
      * Sets the first and last sample frames that will be played in the loop.
      * The ending point must be greater than or equal to the starting point, and
-     * both must fall within the size of the loaded media. A value of 0 for
-     * the starting point means the beginning of the loaded media. Similarly, a
+     * both must fall within the size of the loaded media. A value of 0 for the
+     * starting point means the beginning of the loaded media. Similarly, a
      * value of -1 for the ending point indicates the last frame of the media.
      *
      * @param  start the loop's starting position, in sample frames (zero-based)
-     * @param  end the loop's ending position, in sample frames (zero-based),
-     *         or -1 to indicate the final frame
+     * @param  end the loop's ending position, in sample frames (zero-based), or
+     *         -1 to indicate the final frame
      * @throws IllegalArgumentException if the requested loop points cannot be
      *         set, usually because one or both falls outside the media's
      *         duration or because the ending point is before the starting point
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/CompoundControl.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/CompoundControl.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -90,8 +90,7 @@
 
     /**
      * 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
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Control.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Control.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -48,7 +48,7 @@
     private final Type type;
 
     /**
-     * Constructs a Control with the specified type.
+     * Constructs a control with the specified type.
      *
      * @param  type the kind of control desired
      */
@@ -66,9 +66,9 @@
     }
 
     /**
-     * Obtains a String describing the control type and its current state.
+     * Obtains a string describing the control type and its current state.
      *
-     * @return a String representation of the Control
+     * @return a string representation of the control
      */
     @Override
     public String toString() {
@@ -77,7 +77,6 @@
 
     /**
      * 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 {
 
@@ -98,7 +97,12 @@
         }
 
         /**
-         * 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) {
@@ -106,7 +110,9 @@
         }
 
         /**
-         * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,7 +54,7 @@
  * data, a {@code STOP} event is generated.
  * <p>
  * Mixers often support synchronized control of multiple data lines.
- * Synchronization can be established through the Mixer interface's
+ * Synchronization can be established through the {@code Mixer} interface's
  * {@link Mixer#synchronize synchronize} method. See the description of the
  * {@link Mixer Mixer} interface for a more complete description.
  *
@@ -181,7 +181,7 @@
      * are bytes, but will always correspond to an integral number of sample
      * frames of audio data.
      *
-     * @return the size of the buffer in bytes
+     * @return the size of the buffer, in bytes
      */
     int getBufferSize();
 
@@ -260,8 +260,8 @@
      * {@code DataLine.Info} provides additional information specific to data
      * lines. This information includes:
      * <ul>
-     * <li> the audio formats supported by the data line
-     * <li> the minimum and maximum sizes of its internal buffer
+     *   <li>the audio formats supported by the data line
+     *   <li>the minimum and maximum sizes of its internal buffer
      * </ul>
      * Because a {@code Line.Info} knows the class of the line its describes, a
      * {@code DataLine.Info} object can describe {@code DataLine} subinterfaces
@@ -270,14 +270,25 @@
      * appropriate instance of {@code DataLine.Info} as the argument to a method
      * such as {@link Mixer#getLine(Line.Info)}.
      *
+     * @author Kara Kytle
      * @see Line.Info
-     * @author Kara Kytle
      * @since 1.3
      */
     class Info extends Line.Info {
 
+        /**
+         * The set of supported formats.
+         */
         private final AudioFormat[] formats;
+
+        /**
+         * Minimum buffer size supported by the data line, in bytes.
+         */
         private final int minBufferSize;
+
+        /**
+         * Maximum buffer size supported by the data line, in bytes.
+         */
         private final int maxBufferSize;
 
         /**
@@ -289,10 +300,10 @@
          * @param  lineClass the class of the data line described by the info
          *         object
          * @param  formats set of formats supported
-         * @param  minBufferSize minimum buffer size supported by the data
-         *         line, in bytes
-         * @param  maxBufferSize maximum buffer size supported by the data
-         *         line, in bytes
+         * @param  minBufferSize minimum buffer size supported by the data line,
+         *         in bytes
+         * @param  maxBufferSize maximum buffer size supported by the data line,
+         *         in bytes
          */
         public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
 
@@ -317,7 +328,7 @@
          * @param  lineClass the class of the data line described by the info
          *         object
          * @param  format desired format
-         * @param  bufferSize desired buffer size in bytes
+         * @param  bufferSize desired buffer size, in bytes
          */
         public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {
 
@@ -354,7 +365,7 @@
          * {@code isFormatSupported(AudioFormat)} is guaranteed to return
          * {@code true} for all formats returned by {@code getFormats()}.
          * <p>
-         * Some fields in the AudioFormat instances can be set to
+         * Some fields in the {@code AudioFormat} instances can be set to
          * {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does
          * not apply to the format, or if the format supports a wide range of
          * values for that field. For example, a multi-channel device supporting
@@ -419,6 +430,7 @@
          * large as that of the object specified, and all of its formats must
          * match formats supported by the object specified.
          *
+         * @param  info the info object which is being compared to this one
          * @return {@code true} if this object matches the one specified,
          *         otherwise {@code false}
          */
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Line.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Line.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -237,8 +237,8 @@
          * class. This constructor is typically used by an application to
          * describe a desired line.
          *
-         * @param  lineClass the class of the line that the new Line.Info object
-         *         describes
+         * @param  lineClass the class of the line that the new
+         *         {@code Line.Info} object describes
          */
         public Info(Class<?> lineClass) {
 
@@ -250,7 +250,8 @@
         }
 
         /**
-         * Obtains the class of the line that this Line.Info object describes.
+         * Obtains the class of the line that this {@code Line.Info} object
+         * describes.
          *
          * @return the described line's class
          */
@@ -261,13 +262,13 @@
         /**
          * Indicates whether the specified info object matches this one. To
          * match, the specified object must be identical to or a special case of
-         * this one. The specified info object must be either an instance of
-         * the same class as this one, or an instance of a sub-type of this one.
-         * In addition, the attributes of the specified object must be
-         * compatible with the capabilities of this one. Specifically, the
-         * routing configuration for the specified info object must be
-         * compatible with that of this one. Subclasses may add other criteria
-         * to determine whether the two objects match.
+         * this one. The specified info object must be either an instance of the
+         * same class as this one, or an instance of a sub-type of this one. In
+         * addition, the attributes of the specified object must be compatible
+         * with the capabilities of this one. Specifically, the routing
+         * configuration for the specified info object must be compatible with
+         * that of this one. Subclasses may add other criteria to determine
+         * whether the two objects match.
          *
          * @param  info the info object which is being compared to this one
          * @return {@code true} if the specified object matches this one,
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineEvent.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineEvent.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -48,14 +48,17 @@
  */
 public class LineEvent extends EventObject {
 
+    /**
+     * Use serialVersionUID from JDK 1.3 for interoperability.
+     */
     private static final long serialVersionUID = -1274246333383880410L;
 
     /**
      * The kind of line event ({@code OPEN}, {@code CLOSE}, {@code START}, or
      * {@code STOP}).
      *
+     * @see #getType
      * @serial
-     * @see #getType
      */
     private final Type type;
 
@@ -67,8 +70,8 @@
      * this value is not known, the position value should be
      * {@link AudioSystem#NOT_SPECIFIED}.
      *
+     * @see #getFramePosition
      * @serial
-     * @see #getFramePosition
      */
     private final long position;
 
@@ -184,11 +187,11 @@
 
         /**
          * 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) {
@@ -196,7 +199,9 @@
         }
 
         /**
-         * 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() {
@@ -205,6 +210,8 @@
 
         /**
          * Returns the type name as the string representation.
+         *
+         * @return the type name as the string representation
          */
         @Override
         public String toString() {
@@ -253,22 +260,24 @@
 
         /**
          * A type of event that is sent when a line ceases to engage in active
-         * input or output of audio data because the end of media has been reached.
+         * input or output of audio data because the end of media has been
+         * reached.
          */
         /*
-         * ISSUE: we may want to get rid of this.  Is JavaSound
-         * responsible for reporting this??
+         * ISSUE: we may want to get rid of this. Is JavaSound responsible for
+         * reporting this??
          *
-         * [If it's decided to keep this API, the docs will need to be updated to include mention
-         * of EOM events elsewhere.]
+         * [If it's decided to keep this API, the docs will need to be updated
+         * to include mention of EOM events elsewhere.]
          */
         //public static final Type EOM  = new Type("EOM");
 
         /**
          * A type of event that is sent when a line begins to engage in active
-         * input or output of audio data.  Examples of when this happens are
-         * when a source line begins or resumes writing data to its mixer, and
-         * when a target line begins or resumes reading data from its mixer.
+         * input or output of audio data. Examples of when this happens are when
+         * a source line begins or resumes writing data to its mixer, and when a
+         * target line begins or resumes reading data from its mixer.
+         *
          * @see #STOP
          * @see SourceDataLine#write
          * @see TargetDataLine#read
@@ -277,8 +286,9 @@
         //public static final Type ACTIVE       = new Type("ACTIVE");
 
         /**
-         * A type of event that is sent when a line ceases active input or output
-         * of audio data.
+         * A type of event that is sent when a line ceases active input or
+         * output of audio data.
+         *
          * @see #START
          * @see DataLine#stop
          */
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineUnavailableException.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineUnavailableException.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,6 +35,9 @@
  */
 public class LineUnavailableException extends Exception {
 
+    /**
+     * Use serialVersionUID from JDK 1.3 for interoperability.
+     */
     private static final long serialVersionUID = -2046718279487432130L;
 
     /**
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Mixer.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Mixer.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -58,7 +58,7 @@
      * version, vendor, etc.
      *
      * @return a mixer info object that describes this mixer
-     * @see Mixer.Info
+     * @see Info
      */
     Info getMixerInfo();
 
@@ -144,19 +144,19 @@
     /**
      * Obtains the approximate maximum number of lines of the requested type
      * that can be open simultaneously on the mixer.
-     *
+     * <p>
      * Certain types of mixers do not have a hard bound and may allow opening
      * more lines. Since certain lines are a shared resource, a mixer may not be
      * able to open the maximum number of lines if another process has opened
      * lines of this mixer.
-     *
+     * <p>
      * The requested type is any line that matches the description in the
      * provided {@code Line.Info} object. For example, if the info object
      * represents a speaker port, and the mixer supports exactly one speaker
-     * port, this method should return 1. If the info object represents a
-     * source data line and the mixer supports the use of 32 source data lines
+     * port, this method should return 1. If the info object represents a source
+     * data line and the mixer supports the use of 32 source data lines
      * simultaneously, the return value should be 32. If there is no limit, this
-     * function returns {@code AudioSystem.NOT_SPECIFIED}.
+     * function returns {@link AudioSystem#NOT_SPECIFIED}.
      *
      * @param  info a {@code Line.Info} that describes the line for which the
      *         number of supported instances is queried
@@ -215,11 +215,10 @@
      * this mixer are unsynchronized.
      *
      * @param  lines the synchronized lines for which synchronization should be
-     *         released, or {@code null} for all this mixer's synchronized
-     *         lines
+     *         released, or {@code null} for all this mixer's synchronized lines
      * @throws IllegalArgumentException if the lines cannot be unsynchronized.
-     *         This may occur if the argument specified does not exactly match
-     *         a set of lines for which synchronization has already been
+     *         This may occur if the argument specified does not exactly match a
+     *         set of lines for which synchronization has already been
      *         established.
      */
     void unsynchronize(Line[] lines);
@@ -277,8 +276,8 @@
          * information.
          *
          * @param  name the name of the mixer
-         * @param  vendor the company who manufactures or creates the
-         *         hardware or software mixer
+         * @param  vendor the company who manufactures or creates the hardware
+         *         or software mixer
          * @param  description descriptive text about the mixer
          * @param  version version information for the mixer
          */
@@ -291,13 +290,12 @@
         }
 
         /**
-         * 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
-         * @return {@code true} if this info 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) {
@@ -305,9 +303,9 @@
         }
 
         /**
-         * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Port.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Port.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -100,7 +100,14 @@
         // DAT
         // DVD
 
+        /**
+         * The string that names the port.
+         */
         private final String name;
+
+        /**
+         * Whether this port is source or not.
+         */
         private final boolean isSource;
 
         /**
@@ -111,8 +118,8 @@
          * @param  lineClass the class of the port described by the info object
          * @param  name the string that names the port
          * @param  isSource {@code true} if the port is a source port (such as a
-         *         microphone), {@code false} if the port is a target port
-         *         (such as a speaker)
+         *         microphone), {@code false} if the port is a target port (such
+         *         as a speaker)
          */
         public Info(Class<?> lineClass, String name, boolean isSource) {
 
@@ -134,8 +141,8 @@
          * Indicates whether the port is a source or a target for its mixer.
          *
          * @return {@code true} if the port is a source port (such as a
-         *         microphone), {@code false} if the port is a target port
-         *         (such as a speaker)
+         *         microphone), {@code false} if the port is a target port (such
+         *         as a speaker)
          */
         public boolean isSource() {
             return isSource;
@@ -147,6 +154,8 @@
          * types must be equal.
          *
          * @param  info the info object for which the match is queried
+         * @return {@code true} if the specified object matches this one,
+         *         {@code false} otherwise
          */
         @Override
         public boolean matches(Line.Info info) {
@@ -167,7 +176,12 @@
         }
 
         /**
-         * 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) {
@@ -175,7 +189,9 @@
         }
 
         /**
-         * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/ReverbType.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/ReverbType.java	Thu Aug 31 13:00:23 2017 -0700
@@ -38,7 +38,7 @@
  * delay time and intensity of early reflections, the delay time and intensity
  * of late reflections, and an overall decay time. Early reflections are the
  * initial individual low-order reflections of the direct signal off the
- * surfaces in the room. The late Reflections are the dense, high-order
+ * surfaces in the room. The late reflections are the dense, high-order
  * reflections that characterize the room's reverberation. The delay times for
  * the start of these two reflection types give the listener a sense of the
  * overall size and complexity of the room's shape and contents. The larger the
@@ -63,8 +63,8 @@
  * <p>
  * If implementing JavaSound on a I3DL2-compliant device:
  * <ul>
- * <li>Filtering is disabled (high-frequency attenuations are set to 0.0 dB)
- * <li>Density parameters are set to midway between minimum and maximum
+ *   <li>Filtering is disabled (high-frequency attenuations are set to 0.0 dB)
+ *   <li>Density parameters are set to midway between minimum and maximum
  * </ul>
  * <p>
  * The following table shows what parameter values an implementation might use
@@ -74,60 +74,50 @@
  * <caption>Reverb types and params: decay time, late intensity, late delay,
  * early intensity, and early delay</caption>
  * <thead>
- * <tr>
- *  <th>Type</th>
- *  <th>Decay Time (ms)</th>
- *  <th>Late Intensity (dB)</th>
- *  <th>Late Delay (ms)</th>
- *  <th>Early Intensity (dB)</th>
- *  <th>Early Delay(ms)</th>
- * </tr>
+ *   <tr>
+ *     <th>Type
+ *     <th>Decay Time (ms)
+ *     <th>Late Intensity (dB)
+ *     <th>Late Delay (ms)
+ *     <th>Early Intensity (dB)
+ *     <th>Early Delay(ms)
  * </thead>
  * <tbody>
- * <tr>
- *  <td>Cavern</td>
- *  <td>2250</td>
- *  <td>-2.0</td>
- *  <td>41.3</td>
- *  <td>-1.4</td>
- *  <td>10.3</td>
- * </tr>
- *
- * <tr>
- *  <td>Dungeon</td>
- *  <td>1600</td>
- *  <td>-1.0</td>
- *  <td>10.3</td>
- *  <td>-0.7</td>
- *  <td>2.6</td>
- * </tr>
- *
- * <tr>
- *  <td>Garage</td>
- *  <td>900</td>
- *  <td>-6.0</td>
- *  <td>14.7</td>
- *  <td>-4.0</td>
- *  <td>3.9</td>
- * </tr>
- *
- * <tr>
- *  <td>Acoustic Lab</td>
- *  <td>280</td>
- *  <td>-3.0</td>
- *  <td>8.0</td>
- *  <td>-2.0</td>
- *  <td>2.0</td>
- * </tr>
- *
- * <tr>
- *  <td>Closet</td>
- *  <td>150</td>
- *  <td>-10.0</td>
- *  <td>2.5</td>
- *  <td>-7.0</td>
- *  <td>0.6</td>
- * </tr>
+ *   <tr>
+ *     <td>Cavern
+ *     <td>2250
+ *     <td>-2.0
+ *     <td>41.3
+ *     <td>-1.4
+ *     <td>10.3
+ *   <tr>
+ *     <td>Dungeon
+ *     <td>1600
+ *     <td>-1.0
+ *     <td>10.3
+ *     <td>-0.7
+ *     <td>2.6
+ *   <tr>
+ *     <td>Garage
+ *     <td>900
+ *     <td>-6.0
+ *     <td>14.7
+ *     <td>-4.0
+ *     <td>3.9
+ *   <tr>
+ *     <td>Acoustic Lab
+ *     <td>280
+ *     <td>-3.0
+ *     <td>8.0
+ *     <td>-2.0
+ *     <td>2.0
+ *   <tr>
+ *     <td>Closet
+ *     <td>150
+ *     <td>-10.0
+ *     <td>2.5
+ *     <td>-7.0
+ *     <td>0.6
  * </tbody>
  * </table>
  *
@@ -199,7 +189,7 @@
      * @since 1.5
      */
     public String getName() {
-            return name;
+        return name;
     }
 
     /**
@@ -257,11 +247,11 @@
 
     /**
      * 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) {
@@ -269,7 +259,9 @@
     }
 
     /**
-     * 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() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/SourceDataLine.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/SourceDataLine.java	Thu Aug 31 13:00:23 2017 -0700
@@ -168,9 +168,9 @@
      * {@code IllegalArgumentException}.
      *
      * @param  b a byte array containing data to be written to the data line
+     * @param  off the offset from the beginning of the array, in bytes
      * @param  len the length, in bytes, of the valid data in the array (in
      *         other words, the requested amount of data to write, in bytes)
-     * @param  off the offset from the beginning of the array, in bytes
      * @return the number of bytes actually written
      * @throws IllegalArgumentException if the requested number of bytes does
      *         not represent an integral number of sample frames, or if
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,11 +35,14 @@
  */
 public class UnsupportedAudioFileException extends Exception {
 
+    /**
+     * Use serialVersionUID from JDK 1.3 for interoperability.
+     */
     private static final long serialVersionUID = -139127412623160368L;
 
     /**
-     * Constructs an {@code UnsupportedAudioFileException} that has
-     * {@code null} as its error detail message.
+     * Constructs an {@code UnsupportedAudioFileException} that has {@code null}
+     * as its error detail message.
      */
     public UnsupportedAudioFileException() {
         super();
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/package-info.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/package-info.java	Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
  * <h2>Related Documentation</h2>
  * For more information on using Java Sound see:
  * <ul>
- *     <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- *     The Java Sound Tutorial</a></li>
+ *   <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ *   The Java Sound Tutorial</a>
  * </ul>
  *
  * @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -68,15 +68,15 @@
             throws UnsupportedAudioFileException, IOException;
 
     /**
-     * Obtains the audio file format of the URL provided. The URL must point to
-     * valid audio file data.
+     * Obtains the audio file format of the {@code URL} provided. The
+     * {@code URL} must point to valid audio file data.
      *
-     * @param  url the URL from which file format information should be
+     * @param  url the {@code URL} from which file format information should be
      *         extracted
      * @return an {@code AudioFileFormat} object describing the audio file
      *         format
-     * @throws UnsupportedAudioFileException if the URL does not point to valid
-     *         audio file data recognized by the system
+     * @throws UnsupportedAudioFileException if the {@code URL} does not point
+     *         to valid audio file data recognized by the system
      * @throws IOException if an I/O exception occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
@@ -84,11 +84,11 @@
             throws UnsupportedAudioFileException, IOException;
 
     /**
-     * Obtains the audio file format of the {@code File} provided.
-     * The {@code File} must point to valid audio file data.
+     * Obtains the audio file format of the {@code File} provided. The
+     * {@code File} must point to valid audio file data.
      *
-     * @param  file the {@code File} from which file format information
-     *         should be extracted
+     * @param  file the {@code File} from which file format information should
+     *         be extracted
      * @return an {@code AudioFileFormat} object describing the audio file
      *         format
      * @throws UnsupportedAudioFileException if the {@code File} does not point
@@ -123,15 +123,15 @@
             throws UnsupportedAudioFileException, IOException;
 
     /**
-     * Obtains an audio input stream from the URL provided. The URL must point
-     * to valid audio file data.
+     * Obtains an audio input stream from the {@code URL} provided. The
+     * {@code URL} must point to valid audio file data.
      *
-     * @param  url the URL for which the {@code AudioInputStream} should be
-     *         constructed
+     * @param  url the {@code URL} for which the {@code AudioInputStream} should
+     *         be constructed
      * @return an {@code AudioInputStream} object based on the audio file data
-     *         pointed to by the URL
-     * @throws UnsupportedAudioFileException if the URL does not point to valid
-     *         audio file data recognized by the system
+     *         pointed to by the {@code URL}
+     * @throws UnsupportedAudioFileException if the {@code URL} does not point
+     *         to valid audio file data recognized by the system
      * @throws IOException if an I/O exception occurs
      * @throws NullPointerException if {@code url} is {@code null}
      */
@@ -139,8 +139,8 @@
             throws UnsupportedAudioFileException, IOException;
 
     /**
-     * Obtains an audio input stream from the {@code File} provided.
-     * The {@code File} must point to valid audio file data.
+     * Obtains an audio input stream from the {@code File} provided. The
+     * {@code File} must point to valid audio file data.
      *
      * @param  file the {@code File} for which the {@code AudioInputStream}
      *         should be constructed
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java	Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -113,10 +113,10 @@
 
     /**
      * Writes a stream of bytes representing an audio file of the file type
-     * indicated to the output stream provided. Some file types require that
-     * the length be written into the file header, and cannot be written from
-     * start to finish unless the length is known in advance. An attempt to
-     * write such a file type will fail with an IOException if the length in the
+     * indicated to the output stream provided. Some file types require that the
+     * length be written into the file header, and cannot be written from start
+     * to finish unless the length is known in advance. An attempt to write such
+     * a file type will fail with an {@code IOException} if the length in the
      * audio file format is {@link AudioSystem#NOT_SPECIFIED}.
      *
      * @param  stream the audio input stream containing audio data to be written
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/package-info.java	Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/package-info.java	Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
  * <h2>Related Documentation</h2>
  * For more information on using Java Sound see:
  * <ul>
- *     <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- *     The Java Sound Tutorial</a></li>
+ *   <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ *   The Java Sound Tutorial</a>
  * </ul>
  *
  * @since 1.3