<Sound Dev> RFR JDK 8 8022174 Fix doclint warnings in javax.sound
Sergey Bylokhov
Sergey.Bylokhov at oracle.com
Tue Aug 6 13:34:42 PDT 2013
Hi, Joe.
Looks like in the
AudioFileFormat.java/AudioFormat.java/AudioSystem.java, the new text
should be:
"____ File Format Properties"
like the new text in the MidiFileFormat.java
On 07.08.2013 0:06, Phil Race wrote:
> 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);
>>
>
--
Best regards, Sergey.
More information about the sound-dev
mailing list