8022174: Fix doclint warnings in javax.sound

8022404: Fix doclint issues in java.applet
Reviewed-by: prr

src/share/classes/java/applet/AppletContext.java

 /*
- * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2013, 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
@@ -56,7 +56,7 @@ public interface AppletContext {
 
     /**
      * Returns an <code>Image</code> object that can then be painted on
-     * the screen. The <code>url</code> argument<code> </code>that is
+     * the screen. The <code>url</code> argument that is
      * passed as an argument must specify an absolute URL.
      * <p>
      * This method always returns immediately, whether or not the image
@@ -157,7 +157,7 @@ public interface AppletContext {
      * @param stream stream to be associated with the specified key. If this
      *               parameter is <code>null</code>, the specified key is removed
      *               in this applet context.
-     * @throws <code>IOException</code> if the stream size exceeds a certain
+     * @throws IOException if the stream size exceeds a certain
      *         size limit. Size limit is decided by the implementor of this
      *         interface.
      * @since 1.4

src/share/classes/javax/sound/midi/MetaMessage.java

@@ -149,7 +149,7 @@ public class MetaMessage extends MidiMessage {
      * @param data              the data bytes in the MIDI message
      * @param length    the number of bytes in the <code>data</code>
      * byte array
-     * @throws                  <code>InvalidMidiDataException</code>  if the
+     * @throws                  InvalidMidiDataException  if the
      * parameter values do not specify a valid MIDI meta message
      */
     public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException {

src/share/classes/javax/sound/midi/MidiDevice.java

 /*
- * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -86,13 +86,13 @@ import java.util.List;
  * To detect if a MidiDevice represents a hardware MIDI port, the
  * following programming technique can be used:
  *
- * <pre>
+ * <pre>{@code
  * MidiDevice device = ...;
  * if ( ! (device instanceof Sequencer) && ! (device instanceof Synthesizer)) {
  *   // we're now sure that device represents a MIDI port
  *   // ...
  * }
- * </pre>
+ * }</pre>
  *
  * <p>
  * A <code>MidiDevice</code> includes a <code>{@link MidiDevice.Info}</code> object

src/share/classes/javax/sound/midi/MidiDeviceReceiver.java

 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2013, 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
@@ -33,7 +33,9 @@ package javax.sound.midi;
  * @since 1.7
  */
 public interface MidiDeviceReceiver extends Receiver {
-    /** Obtains a MidiDevice object which is an owner of this Receiver.
+    /**
+     * Obtains a MidiDevice object which is an owner of this Receiver.
+     * @return a MidiDevice object which is an owner of this Receiver
      */
     public MidiDevice getMidiDevice();
 }

src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java

 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2013, 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,7 +35,9 @@ package javax.sound.midi;
  */
 public interface MidiDeviceTransmitter extends Transmitter {
 
-    /** Obtains a MidiDevice object which is an owner of this Transmitter.
+    /**
+     * Obtains a MidiDevice object which is an owner of this Transmitter.
+     * @return a MidiDevice object which is an owner of this Transmitter
      */
     public MidiDevice getMidiDevice();
 }

src/share/classes/javax/sound/midi/MidiFileFormat.java

 /*
- * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -50,6 +50,7 @@ import java.util.Map;
  * be used in implementations:
  *
  * <table border=1>
+    <caption>MIDI File Format Properties</caption>
  *  <tr>
  *   <th>Property key</th>
  *   <th>Value type</th>

src/share/classes/javax/sound/midi/MidiMessage.java

 /*
- * Copyright (c) 1998, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, 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
@@ -55,7 +55,7 @@ package javax.sound.midi;
  * processing MIDI data that originated outside Java Sound and now
  * is encoded as signed bytes, the bytes can
  * can be converted to integers using this conversion:
- * <center><code>int i = (int)(byte & 0xFF)</code></center>
+ * <center>{@code int i = (int)(byte & 0xFF)}</center>
  * <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
@@ -118,6 +118,10 @@ public abstract class MidiMessage implements Cloneable {
      * method is called by concrete subclasses, which should
      * ensure that the data array specifies a complete, valid MIDI
      * message.
+     *
+     * @param data the data bytes in the MIDI message
+     * @param length the number of bytes in the data byte array
+     * @throws InvalidMidiDataException if the parameter values do not specify a valid MIDI meta message
      */
     protected void setMessage(byte[] data, int length) throws InvalidMidiDataException {
         if (length < 0 || (length > 0 && length > data.length)) {

src/share/classes/javax/sound/midi/MidiSystem.java

 /*
- * Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -80,6 +80,7 @@ import com.sun.media.sound.MidiDeviceTransmitterEnvelope;
  * consider them:
  *
  * <table border=0>
+ *  <caption>MIDI System Property Keys</caption>
  *  <tr>
  *   <th>Property Key</th>
  *   <th>Interface</th>
@@ -425,6 +426,8 @@ public class MidiSystem {
      * it is used to identify the default sequencer.
      * For details, refer to the {@link MidiSystem class description}.
      *
+     * @param connected whether or not the returned {@code Sequencer}
+     * is connected to the default {@code Synthesizer}
      * @return the default sequencer
      * @throws MidiUnavailableException if the sequencer is not
      *         available due to resource restrictions,

src/share/classes/javax/sound/midi/ShortMessage.java

 /*
- * Copyright (c) 1998, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, 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
@@ -283,7 +283,7 @@ public class ShortMessage extends MidiMessage {
     /**
      * Sets the parameters for a MIDI message that takes no data bytes.
      * @param status    the MIDI status byte
-     * @throws  <code>InvalidMidiDataException</code> if <code>status</code> does not
+     * @throws  InvalidMidiDataException if <code>status</code> does not
      * specify a valid MIDI status byte for a message that requires no data bytes.
      * @see #setMessage(int, int, int)
      * @see #setMessage(int, int, int, int)
@@ -307,7 +307,7 @@ public class ShortMessage extends MidiMessage {
      * @param status    the MIDI status byte
      * @param data1             the first data byte
      * @param data2             the second data byte
-     * @throws  <code>InvalidMidiDataException</code> if the
+     * @throws  InvalidMidiDataException if the
      * the status byte, or all data bytes belonging to the message, do
      * not specify a valid MIDI message.
      * @see #setMessage(int, int, int, int)
@@ -357,7 +357,7 @@ public class ShortMessage extends MidiMessage {
      * @param channel   the channel associated with the message
      * @param data1             the first data byte
      * @param data2             the second data byte
-     * @throws          <code>InvalidMidiDataException</code> if the
+     * @throws          InvalidMidiDataException if the
      * status byte or all data bytes belonging to the message, do
      * not specify a valid MIDI message
      *
@@ -397,6 +397,7 @@ public class ShortMessage extends MidiMessage {
      * Obtains the MIDI command associated with this event.  This method
      * assumes that the event is a MIDI channel message; if not, the return
      * value will not be meaningful.
+     * @return the MIDI command associated with this event
      * @see #setMessage(int, int, int, int)
      */
     public int getCommand() {
@@ -450,7 +451,7 @@ public class ShortMessage extends MidiMessage {
      * status byte value.
      * @param status status byte value, which must represent a short MIDI message
      * @return data length in bytes (0, 1, or 2)
-     * @throws <code>InvalidMidiDataException</code> if the
+     * @throws InvalidMidiDataException if the
      * <code>status</code> argument does not represent the status byte for any
      * short message
      */

src/share/classes/javax/sound/midi/Synthesizer.java

 /*
- * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -170,7 +170,7 @@ public interface Synthesizer extends MidiDevice {
      * already had been), <code>false</code> if the instrument could not be
      * loaded (for example, if the synthesizer has insufficient
      * memory to load it)
-     * @throws <code>IllegalArgumentException</code> if this
+     * @throws IllegalArgumentException if this
      * <code>Synthesizer</code> doesn't support the specified instrument's
      * soundbank
      * @see #unloadInstrument
@@ -186,7 +186,7 @@ public interface Synthesizer extends MidiDevice {
     /**
      * Unloads a particular instrument.
      * @param instrument instrument to unload
-     * @throws <code>IllegalArgumentException</code> if this
+     * @throws IllegalArgumentException if this
      * <code>Synthesizer</code> doesn't support the specified instrument's
      * soundbank
      * @see #loadInstrument
@@ -214,10 +214,10 @@ public interface Synthesizer extends MidiDevice {
      * of the old instrument, it should be loaded into the synthesizer
      * @return <code>true</code> if the instrument succeessfully remapped,
      * <code>false</code> if feature is not implemented by synthesizer
-     * @throws <code>IllegalArgumentException</code> if instrument
+     * @throws IllegalArgumentException if instrument
      * <code>from</code> or instrument <code>to</code> aren't supported by
      * synthesizer or if instrument <code>to</code> is not loaded
-     * @throws <code>NullPointerException</code> if <code>from</code> or
+     * @throws NullPointerException if <code>from</code> or
      * <code>to</code> parameters have null value
      * @see #loadInstrument
      * @see #loadInstruments

src/share/classes/javax/sound/midi/SysexMessage.java

 /*
- * Copyright (c) 1998, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, 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
@@ -204,6 +204,7 @@ public class SysexMessage extends MidiMessage {
      * @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
      */
     public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException {
         if ( (status != 0xF0) && (status != 0xF7) ) {

src/share/classes/javax/sound/midi/Track.java

 /*
- * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -211,10 +211,11 @@ public class Track {
     /**
      * Obtains the event at the specified index.
      * @param index the location of the desired event in the event vector
-     * @throws <code>ArrayIndexOutOfBoundsException</code>  if the
+     * @throws ArrayIndexOutOfBoundsException  if the
      * specified index is negative or not less than the current size of
      * this track.
      * @see #size
+     * @return the event at the specified index
      */
     public MidiEvent get(int index) throws ArrayIndexOutOfBoundsException {
         try {

src/share/classes/javax/sound/sampled/AudioFileFormat.java

 /*
- * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -57,6 +57,7 @@ import java.util.Map;
  * be used in implementations:
  *
  * <table border=1>
+ *  <caption>Audio File Format Property Keys</caption>
  *  <tr>
  *   <th>Property key</th>
  *   <th>Value type</th>

src/share/classes/javax/sound/sampled/AudioFormat.java

 /*
- * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -85,6 +85,7 @@ import java.util.Map;
  * service providers should use, if applicable:
  *
  * <table border=0>
+ *  <caption>Audio Format Property Keys</caption>
  *  <tr>
  *   <th>Property key</th>
  *   <th>Value type</th>

src/share/classes/javax/sound/sampled/AudioSystem.java

 /*
- * Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -75,6 +75,7 @@ import com.sun.media.sound.JDK13Services;
  * consider them:
  *
  * <table border=0>
+ *  <caption>Audio System Property Keys</caption>
  *  <tr>
  *   <th>Property Key</th>
  *   <th>Interface</th>

src/share/classes/javax/sound/sampled/BooleanControl.java

 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -125,6 +125,7 @@ public abstract class BooleanControl extends Control {
 
     /**
      * Obtains the label for the specified state.
+     * @param state the state whose label will be returned
      * @return the label for the specified state, such as "true" or "on"
      * for <code>true</code>, or "false" or "off" for <code>false</code>.
      */

src/share/classes/javax/sound/sampled/Mixer.java

 /*
- * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -133,6 +133,8 @@ public interface Mixer extends Line {
      * <code>DataLine</code>.
      *
      * @param info describes the desired line
+     * @return a line that is available for use and that matches the description
+     * in the specified {@code Line.Info} object
      * @throws LineUnavailableException if a matching line
      * is not available due to resource restrictions
      * @throws IllegalArgumentException if this mixer does

src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java

 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, 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
@@ -116,6 +116,7 @@ public abstract class FormatConversionProvider {
      * given a particular source format.
      * If no target format encodings are supported for this source format,
      * an array of length 0 is returned.
+     * @param sourceFormat format of the incoming data
      * @return array of supported target format encodings.
      */
     public abstract AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat);
@@ -146,6 +147,8 @@ public abstract class FormatConversionProvider {
      * supported by the format converter
      * If no target formats with the specified encoding are supported
      * for this source format, an array of length 0 is returned.
+     * @param targetEncoding desired encoding of the stream after processing
+     * @param sourceFormat format of the incoming data
      * @return array of supported target formats.
      */
     public abstract AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat);