8037117: Javadoc cleanup of javax.sound.midi.spi package

Reviewed-by: art, pchelko

src/share/classes/javax/sound/midi/spi/MidiDeviceProvider.java

 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, 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
@@ -26,26 +26,24 @@
 package javax.sound.midi.spi;
 
 import javax.sound.midi.MidiDevice;
-import javax.sound.midi.MidiUnavailableException;
 
 /**
- * A <code>MidiDeviceProvider</code> is a factory or provider for a particular
- * type of MIDI device.
- * This mechanism allows the implementation to determine
- * how resources are managed in the creation and management of
- * a device.
+ * A {@code MidiDeviceProvider} is a factory or provider for a particular type
+ * of MIDI device. This mechanism allows the implementation to determine how
+ * resources are managed in the creation and management of a device.
  *
  * @author Kara Kytle
  */
 public abstract class MidiDeviceProvider {
 
-
     /**
      * Indicates whether the device provider supports the device represented by
      * the specified device info object.
-     * @param info an info object that describes the device for which support is queried
-     * @return <code>true</code> if the specified device is supported,
-     * otherwise <code>false</code>
+     *
+     * @param  info an info object that describes the device for which support
+     *         is queried
+     * @return {@code true} if the specified device is supported, otherwise
+     *         {@code false}
      */
     public boolean isDeviceSupported(MidiDevice.Info info) {
 
@@ -59,21 +57,22 @@ public abstract class MidiDeviceProvider {
         return false;
     }
 
-
     /**
-     * Obtains the set of info objects representing the device
-     * or devices provided by this <code>MidiDeviceProvider</code>.
+     * Obtains the set of info objects representing the device or devices
+     * provided by this {@code MidiDeviceProvider}.
+     *
      * @return set of device info objects
      */
     public abstract MidiDevice.Info[] getDeviceInfo();
 
-
     /**
      * Obtains an instance of the device represented by the info object.
-     * @param info an info object that describes the desired device
+     *
+     * @param  info an info object that describes the desired device
      * @return device instance
      * @throws IllegalArgumentException if the info object specified does not
-     * match the info object for a device supported by this <code>MidiDeviceProvider</code>.
+     *         match the info object for a device supported by this
+     *         {@code MidiDeviceProvider}
      */
     public abstract MidiDevice getDevice(MidiDevice.Info info);
 }

src/share/classes/javax/sound/midi/spi/MidiFileReader.java

 /*
- * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, 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,10 @@ import javax.sound.midi.Sequence;
 import javax.sound.midi.InvalidMidiDataException;
 
 /**
- * A <code>MidiFileReader</code> supplies MIDI file-reading services.  Classes implementing this
- * interface can parse the format information from one or more types of
- * MIDI file, and can produce a <code>Sequence</code> object from files of these types.
+ * A {@code MidiFileReader} supplies MIDI file-reading services. Classes
+ * implementing this interface can parse the format information from one or more
+ * types of MIDI file, and can produce a {@link Sequence} object from files of
+ * these types.
  *
  * @author Kara Kytle
  * @since 1.3
@@ -45,98 +46,102 @@ import javax.sound.midi.InvalidMidiDataException;
 public abstract class MidiFileReader {
 
     /**
-     * Obtains the MIDI file format of the input stream provided.  The stream must
-     * point to valid MIDI file data.  In general, MIDI file readers may
+     * Obtains the MIDI file format of the input stream provided. The stream
+     * must point to valid MIDI file data. In general, MIDI file readers may
      * need to read some data from the stream before determining whether they
-     * support 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 <code>IOException</code>.
-     * @param stream the input stream from which file format information should be
-     * extracted
-     * @return a <code>MidiFileFormat</code> object describing the MIDI file format
-     * @throws InvalidMidiDataException if the stream does not point to valid MIDI
-     * file data recognized by the system
+     * support 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 {@code IOException}.
+     *
+     * @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
      * @throws IOException if an I/O exception occurs
      * @see InputStream#markSupported
      * @see InputStream#mark
      */
-    public abstract MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException;
-
+    public abstract MidiFileFormat getMidiFileFormat(InputStream stream)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains the MIDI file format of the URL provided.  The URL must
-     * point to valid MIDI file data.
-     * @param url the URL from which file format information should be
-     * extracted
-     * @return a <code>MidiFileFormat</code> object describing the MIDI file format
+     * Obtains the MIDI file format of the URL provided. The URL must point to
+     * valid MIDI file data.
+     *
+     * @param  url the 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
+     *         file data recognized by the system
      * @throws IOException if an I/O exception occurs
      */
-    public abstract MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, IOException;
-
+    public abstract MidiFileFormat getMidiFileFormat(URL url)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains the MIDI file format of the <code>File</code> provided.
-     * The <code>File</code> must point to valid MIDI file data.
-     * @param file the <code>File</code> from which file format information should be
-     * extracted
-     * @return a <code>MidiFileFormat</code> object describing the MIDI file format
-     * @throws InvalidMidiDataException if the <code>File</code> does not point to valid MIDI
-     * file data recognized by the system
+     * Obtains the MIDI file format of the {@code File} provided. The
+     * {@code File} must point to valid MIDI file data.
+     *
+     * @param  file the {@code File} from which file format information should
+     *         be extracted
+     * @return a {@code MidiFileFormat} object describing the MIDI file format
+     * @throws InvalidMidiDataException if the {@code File} does not point to
+     *         valid MIDI file data recognized by the system
      * @throws IOException if an I/O exception occurs
      */
-    public abstract MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException;
-
+    public abstract MidiFileFormat getMidiFileFormat(File file)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains a MIDI sequence from the input stream provided.  The stream must
-     * point to valid MIDI file data.  In general, MIDI file readers may
-     * need to read some data from the stream before determining whether they
-     * support 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.
-     * @param stream the input stream from which the <code>Sequence</code> should be
-     * constructed
-     * @return a <code>Sequence</code> object based on the MIDI file data contained
-     * in the input stream.
-     * @throws InvalidMidiDataException if the stream does not point to valid MIDI
-     * file data recognized by the system
+     * Obtains a MIDI sequence from the input stream provided. The stream must
+     * point to valid MIDI file data. In general, MIDI file readers may need to
+     * read some data from the stream before determining whether they support
+     * 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.
+     *
+     * @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
+     *         MIDI file data recognized by the system
      * @throws IOException if an I/O exception occurs
      * @see InputStream#markSupported
      * @see InputStream#mark
      */
-    public abstract Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException;
-
+    public abstract Sequence getSequence(InputStream stream)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains a MIDI sequence from the URL provided.  The URL must
-     * point to valid MIDI file data.
-     * @param url the URL for which the <code>Sequence</code> should be
-     * constructed
-     * @return a <code>Sequence</code> object based on the MIDI file data pointed
-     * to by the URL
+     * Obtains a MIDI sequence from the URL provided. The URL must point to
+     * valid MIDI file data.
+     *
+     * @param  url the 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
+     *         file data recognized by the system
      * @throws IOException if an I/O exception occurs
      */
-    public abstract Sequence getSequence(URL url) throws InvalidMidiDataException, IOException;
-
+    public abstract Sequence getSequence(URL url)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains a MIDI sequence from the <code>File</code> provided.  The <code>File</code> must
-     * point to valid MIDI file data.
-     * @param file the <code>File</code> from which the <code>Sequence</code> should be
-     * constructed
-     * @return a <code>Sequence</code> object based on the MIDI file data pointed
-     * to by the <code>File</code>
-     * @throws InvalidMidiDataException if the <code>File</code> does not point to valid MIDI
-     * file data recognized by the system
+     * Obtains a MIDI sequence from the {@code File} provided. The {@code File}
+     * must point to valid MIDI file data.
+     *
+     * @param  file the {@code File} from which the {@code Sequence} should be
+     *         constructed
+     * @return a {@code Sequence} object based on the MIDI file data pointed to
+     *         by the {@code File}
+     * @throws InvalidMidiDataException if the {@code File} does not point to
+     *         valid MIDI file data recognized by the system
      * @throws IOException if an I/O exception occurs
      */
-    public abstract Sequence getSequence(File file) throws InvalidMidiDataException, IOException;
+    public abstract Sequence getSequence(File file)
+            throws InvalidMidiDataException, IOException;
 }

src/share/classes/javax/sound/midi/spi/MidiFileWriter.java

 /*
- * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, 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
@@ -30,45 +30,44 @@ import java.io.IOException;
 import java.io.OutputStream;
 
 import javax.sound.midi.Sequence;
-import javax.sound.midi.MidiFileFormat;
 
 /**
- * A <code>MidiFileWriter</code> supplies MIDI file-writing services.  Classes
- * that implement this interface can write one or more types of MIDI file from
- * a <code>{@link Sequence}</code> object.
+ * A {@code MidiFileWriter} supplies MIDI file-writing services. Classes that
+ * implement this interface can write one or more types of MIDI file from a
+ * {@link Sequence} object.
  *
  * @author Kara Kytle
  * @since 1.3
  */
 public abstract class MidiFileWriter {
 
-
     /**
      * Obtains the set of MIDI file types for which file writing support is
      * provided by this file writer.
-     * @return array of file types.  If no file types are supported,
-     * an array of length 0 is returned.
+     *
+     * @return array of file types. If no file types are supported, an array of
+     *         length 0 is returned.
      */
     public abstract int[] getMidiFileTypes();
 
-
     /**
-     * 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
-     * @return array of file types.  If no file types are supported,
-     * returns an array of length 0.
+     * 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
+     * @return array of file types. If no file types are supported, returns an
+     *         array of length 0.
      */
     public abstract int[] getMidiFileTypes(Sequence sequence);
 
-
     /**
      * Indicates whether file writing support for the specified MIDI file type
      * is provided by this file writer.
-     * @param fileType the file type for which write capabilities are queried
-     * @return <code>true</code> if the file type is supported,
-     * otherwise <code>false</code>
+     *
+     * @param  fileType the file type for which write capabilities are queried
+     * @return {@code true} if the file type is supported, otherwise
+     *         {@code false}
      */
     public boolean isFileTypeSupported(int fileType) {
 
@@ -81,14 +80,14 @@ public abstract class MidiFileWriter {
         return false;
     }
 
-
     /**
      * Indicates whether a MIDI file of the file type specified can be written
      * from the sequence indicated.
-     * @param fileType the file type for which write capabilities are queried
-     * @param sequence  the sequence for which file writing support is queried
-     * @return <code>true</code> if the file type is supported for this sequence,
-     * otherwise <code>false</code>
+     *
+     * @param  fileType the file type for which write capabilities are queried
+     * @param  sequence the sequence for which file writing support is queried
+     * @return {@code true} if the file type is supported for this sequence,
+     *         otherwise {@code false}
      */
     public boolean isFileTypeSupported(int fileType, Sequence sequence) {
 
@@ -101,35 +100,38 @@ public abstract class MidiFileWriter {
         return false;
     }
 
-
     /**
      * Writes a stream of bytes representing a MIDI file of the file type
      * indicated to the output stream provided.
-     * @param in sequence containing MIDI data to be written to the file
-     * @param fileType type of the file to be written to the output stream
-     * @param out stream to which the file data should be written
+     *
+     * @param  in sequence containing MIDI data to be written to the file
+     * @param  fileType type of the file to be written to the output stream
+     * @param  out stream to which the file data should be written
      * @return the number of bytes written to the output stream
      * @throws IOException if an I/O exception occurs
      * @throws IllegalArgumentException if the file type is not supported by
-     * this file writer
+     *         this file writer
      * @see #isFileTypeSupported(int, Sequence)
-     * @see     #getMidiFileTypes(Sequence)
+     * @see #getMidiFileTypes(Sequence)
      */
-    public abstract int write(Sequence in, int fileType, OutputStream out) throws IOException;
-
+    public abstract int write(Sequence in, int fileType, OutputStream out)
+            throws IOException;
 
     /**
      * Writes a stream of bytes representing a MIDI file of the file type
      * indicated to the external file provided.
-     * @param in sequence containing MIDI data to be written to the external file
-     * @param fileType type of the file to be written to the external file
-     * @param out external file to which the file data should be written
+     *
+     * @param  in sequence containing MIDI data to be written to the external
+     *         file
+     * @param  fileType type of the file to be written to the external file
+     * @param  out external file to which the file data should be written
      * @return the number of bytes written to the file
      * @throws IOException if an I/O exception occurs
      * @throws IllegalArgumentException if the file type is not supported by
-     * this file writer
+     *         this file writer
      * @see #isFileTypeSupported(int, Sequence)
-     * @see     #getMidiFileTypes(Sequence)
+     * @see #getMidiFileTypes(Sequence)
      */
-    public abstract int write(Sequence in, int fileType, File out) throws IOException;
+    public abstract int write(Sequence in, int fileType, File out)
+            throws IOException;
 }

src/share/classes/javax/sound/midi/spi/SoundbankReader.java

 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, 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
@@ -25,60 +25,58 @@
 
 package javax.sound.midi.spi;
 
-import java.io.InputStream;
-import java.io.IOException;
 import java.io.File;
-
+import java.io.IOException;
+import java.io.InputStream;
 import java.net.URL;
 
-import javax.sound.midi.Soundbank;
 import javax.sound.midi.InvalidMidiDataException;
-
+import javax.sound.midi.Soundbank;
 
 /**
- * A <code>SoundbankReader</code> supplies soundbank file-reading services.
- * Concrete subclasses of <code>SoundbankReader</code> parse a given
- * soundbank file, producing a {@link javax.sound.midi.Soundbank}
- * object that can be loaded into a {@link javax.sound.midi.Synthesizer}.
+ * A {@code SoundbankReader} supplies soundbank file-reading services. Concrete
+ * subclasses of {@code SoundbankReader} parse a given soundbank file, producing
+ * a {@link javax.sound.midi.Soundbank} object that can be loaded into a
+ * {@link javax.sound.midi.Synthesizer}.
  *
  * @since 1.3
  * @author Kara Kytle
  */
 public abstract class SoundbankReader {
 
-
     /**
      * Obtains a soundbank object from the URL provided.
-     * @param url URL representing the soundbank.
+     *
+     * @param  url 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 URL does not point to valid MIDI
+     *         soundbank data recognized by this soundbank reader
      * @throws IOException if an I/O error occurs
      */
-    public abstract Soundbank getSoundbank(URL url) throws InvalidMidiDataException, IOException;
-
+    public abstract Soundbank getSoundbank(URL url)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains a soundbank object from the <code>InputStream</code> provided.
-     * @param stream <code>InputStream</code> representing the soundbank
+     * Obtains a soundbank object from the {@code InputStream} provided.
+     *
+     * @param  stream {@code InputStream} representing the soundbank
      * @return soundbank object
-     * @throws InvalidMidiDataException if the stream does not point to
-     * valid MIDI soundbank data recognized by this soundbank reader
+     * @throws InvalidMidiDataException if the stream does not point to valid
+     *         MIDI soundbank data recognized by this soundbank reader
      * @throws IOException if an I/O error occurs
      */
-    public abstract Soundbank getSoundbank(InputStream stream) throws InvalidMidiDataException, IOException;
-
+    public abstract Soundbank getSoundbank(InputStream stream)
+            throws InvalidMidiDataException, IOException;
 
     /**
-     * Obtains a soundbank object from the <code>File</code> provided.
-     * @param file the <code>File</code> representing the soundbank
+     * Obtains a soundbank object from the {@code File} provided.
+     *
+     * @param  file the {@code File} representing the soundbank
      * @return soundbank object
-     * @throws InvalidMidiDataException if the file does not point to
-     * valid MIDI soundbank data recognized by this soundbank reader
+     * @throws InvalidMidiDataException if the file does not point to valid MIDI
+     *         soundbank data recognized by this soundbank reader
      * @throws IOException if an I/O error occurs
      */
-    public abstract Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException;
-
-
-
+    public abstract Soundbank getSoundbank(File file)
+            throws InvalidMidiDataException, IOException;
 }