<Sound Dev> RFR JDK 8 8022174 Fix doclint warnings in javax.sound
Sergey Bylokhov
Sergey.Bylokhov at oracle.com
Tue Aug 6 13:43:51 PDT 2013
I assume that text in AudioFileFormat.java/AudioFormat.java was copied
from the AudioSystem. And yes AudioSystem contains list of keys, but
that's not true for AudioFileFormat.java/AudioFormat.java
On 07.08.2013 0:34, Sergey Bylokhov wrote:
> 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