<Sound Dev> RFR JDK 8 8022174 Fix doclint warnings in javax.sound

Phil Race philip.race at oracle.com
Tue Aug 6 13:06:15 PDT 2013


Looks fine to me.

-phil.

On 8/5/13 11:23 PM, Joe Darcy wrote:
> Hello,
>
> Please review this fix for all of the doclint issues in javax.sound.*:
>
>     http://cr.openjdk.java.net/~darcy/8022174.0/
>
> Patch below.
>
> Thanks,
>
> -Joe
>
> --- old/src/share/classes/javax/sound/midi/MetaMessage.java 2013-08-05 
> 23:20:39.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MetaMessage.java 2013-08-05 
> 23:20:38.000000000 -0700
> @@ -149,7 +149,7 @@
>       * @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 {
> --- old/src/share/classes/javax/sound/midi/MidiDevice.java 2013-08-05 
> 23:20:39.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MidiDevice.java 2013-08-05 
> 23:20:39.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * 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
> --- old/src/share/classes/javax/sound/midi/MidiDeviceReceiver.java 
> 2013-08-05 23:20:39.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MidiDeviceReceiver.java 
> 2013-08-05 23:20:39.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * @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();
>  }
> --- old/src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java 
> 2013-08-05 23:20:40.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java 
> 2013-08-05 23:20:40.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   */
>  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();
>  }
> --- old/src/share/classes/javax/sound/midi/MidiFileFormat.java 
> 2013-08-05 23:20:40.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MidiFileFormat.java 
> 2013-08-05 23:20:40.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * be used in implementations:
>   *
>   * <table border=1>
> +    <caption>MIDI File Format Properties</caption>
>   *  <tr>
>   *   <th>Property key</th>
>   *   <th>Value type</th>
> --- old/src/share/classes/javax/sound/midi/MidiMessage.java 2013-08-05 
> 23:20:41.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MidiMessage.java 2013-08-05 
> 23:20:41.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * 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 @@
>       * 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)) {
> --- old/src/share/classes/javax/sound/midi/MidiSystem.java 2013-08-05 
> 23:20:41.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/MidiSystem.java 2013-08-05 
> 23:20:41.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * consider them:
>   *
>   * <table border=0>
> + *  <caption>MIDI System Property Keys</caption>
>   *  <tr>
>   *   <th>Property Key</th>
>   *   <th>Interface</th>
> @@ -425,6 +426,8 @@
>       * 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,
> --- old/src/share/classes/javax/sound/midi/ShortMessage.java 
> 2013-08-05 23:20:42.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/ShortMessage.java 
> 2013-08-05 23:20:41.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>      /**
>       * 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 @@
>       * @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 @@
>       * @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 @@
>       * 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 @@
>       * 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
>       */
> --- old/src/share/classes/javax/sound/midi/Synthesizer.java 2013-08-05 
> 23:20:42.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/Synthesizer.java 2013-08-05 
> 23:20:42.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>       * 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 @@
>      /**
>       * 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 @@
>       * 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
> --- old/src/share/classes/javax/sound/midi/SysexMessage.java 
> 2013-08-05 23:20:43.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/SysexMessage.java 
> 2013-08-05 23:20:43.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>       * @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) ) {
> --- old/src/share/classes/javax/sound/midi/Track.java 2013-08-05 
> 23:20:43.000000000 -0700
> +++ new/src/share/classes/javax/sound/midi/Track.java 2013-08-05 
> 23:20:43.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>      /**
>       * 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 {
> --- old/src/share/classes/javax/sound/sampled/AudioFileFormat.java 
> 2013-08-05 23:20:44.000000000 -0700
> +++ new/src/share/classes/javax/sound/sampled/AudioFileFormat.java 
> 2013-08-05 23:20:43.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * be used in implementations:
>   *
>   * <table border=1>
> + *  <caption>Audio File Format Property Keys</caption>
>   *  <tr>
>   *   <th>Property key</th>
>   *   <th>Value type</th>
> --- old/src/share/classes/javax/sound/sampled/AudioFormat.java 
> 2013-08-05 23:20:44.000000000 -0700
> +++ new/src/share/classes/javax/sound/sampled/AudioFormat.java 
> 2013-08-05 23:20:44.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * service providers should use, if applicable:
>   *
>   * <table border=0>
> + *  <caption>Audio Format Property Keys</caption>
>   *  <tr>
>   *   <th>Property key</th>
>   *   <th>Value type</th>
> --- old/src/share/classes/javax/sound/sampled/AudioSystem.java 
> 2013-08-05 23:20:44.000000000 -0700
> +++ new/src/share/classes/javax/sound/sampled/AudioSystem.java 
> 2013-08-05 23:20:44.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>   * consider them:
>   *
>   * <table border=0>
> + *  <caption>Audio System Property Keys</caption>
>   *  <tr>
>   *   <th>Property Key</th>
>   *   <th>Interface</th>
> --- old/src/share/classes/javax/sound/sampled/BooleanControl.java 
> 2013-08-05 23:20:45.000000000 -0700
> +++ new/src/share/classes/javax/sound/sampled/BooleanControl.java 
> 2013-08-05 23:20:45.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>
>      /**
>       * 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>.
>       */
> --- old/src/share/classes/javax/sound/sampled/Mixer.java 2013-08-05 
> 23:20:45.000000000 -0700
> +++ new/src/share/classes/javax/sound/sampled/Mixer.java 2013-08-05 
> 23:20:45.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>       * <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
> --- 
> old/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java 
> 2013-08-05 23:20:46.000000000 -0700
> +++ 
> new/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java 
> 2013-08-05 23:20:45.000000000 -0700
> @@ -1,5 +1,5 @@
>  /*
> - * 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 @@
>       * 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 @@
>       * 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);
>



More information about the sound-dev mailing list