From philip.race at oracle.com Tue Aug 6 13:06:15 2013 From: philip.race at oracle.com (Phil Race) Date: Tue, 06 Aug 2013 13:06:15 -0700 Subject: RFR JDK 8 8022174 Fix doclint warnings in javax.sound In-Reply-To: <52009654.9030509@oracle.com> References: <52009654.9030509@oracle.com> Message-ID: <52015737.80506@oracle.com> 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 data > * byte array > - * @throws InvalidMidiDataException 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: > * > - *
> + * 
{@code
>   * MidiDevice device = ...;
>   * if ( ! (device instanceof Sequencer) && ! (device instanceof 
> Synthesizer)) {
>   *   // we're now sure that device represents a MIDI port
>   *   // ...
>   * }
> - * 
> + * }
> * > *

> * A MidiDevice includes a {@link > MidiDevice.Info} 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: > * > * > + > * > * > * > --- 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: > - *
int i = (int)(byte & 0xFF)
> + *
{@code int i = (int)(byte & 0xFF)}
> *

> * 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: > * > *

MIDI File Format Properties
Property keyValue type
> + * > * > * > * > @@ -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 InvalidMidiDataException if > status does not > + * @throws InvalidMidiDataException if status 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 InvalidMidiDataException 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 InvalidMidiDataException 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 InvalidMidiDataException if the > + * @throws InvalidMidiDataException if the > * status 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), false if the instrument could > not be > * loaded (for example, if the synthesizer has insufficient > * memory to load it) > - * @throws IllegalArgumentException if this > + * @throws IllegalArgumentException if this > * Synthesizer doesn't support the specified > instrument's > * soundbank > * @see #unloadInstrument > @@ -186,7 +186,7 @@ > /** > * Unloads a particular instrument. > * @param instrument instrument to unload > - * @throws IllegalArgumentException if this > + * @throws IllegalArgumentException if this > * Synthesizer 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 true if the instrument succeessfully > remapped, > * false if feature is not implemented by synthesizer > - * @throws IllegalArgumentException if instrument > + * @throws IllegalArgumentException if instrument > * from or instrument to aren't > supported by > * synthesizer or if instrument to is not loaded > - * @throws NullPointerException if from or > + * @throws NullPointerException if from or > * to 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 ArrayIndexOutOfBoundsException 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: > * > *
MIDI System Property Keys
Property KeyInterface
> + * > * > * > * > --- 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: > * > *
Audio File Format Property Keys
Property keyValue type
> + * > * > * > * > --- 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: > * > *
Audio Format Property Keys
Property keyValue type
> + * > * > * > * > --- 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 true, or "false" or "off" for > false. > */ > --- 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 @@ > * DataLine. > * > * @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); > From Sergey.Bylokhov at oracle.com Tue Aug 6 13:34:42 2013 From: Sergey.Bylokhov at oracle.com (Sergey Bylokhov) Date: Wed, 07 Aug 2013 00:34:42 +0400 Subject: RFR JDK 8 8022174 Fix doclint warnings in javax.sound In-Reply-To: <52015737.80506@oracle.com> References: <52009654.9030509@oracle.com> <52015737.80506@oracle.com> Message-ID: <52015DE2.1080404@oracle.com> 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 data >> * byte array >> - * @throws InvalidMidiDataException 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: >> * >> - *
>> + * 
{@code
>>   * MidiDevice device = ...;
>>   * if ( ! (device instanceof Sequencer) && ! (device instanceof 
>> Synthesizer)) {
>>   *   // we're now sure that device represents a MIDI port
>>   *   // ...
>>   * }
>> - * 
>> + * }
>> * >> *

>> * A MidiDevice includes a {@link >> MidiDevice.Info} 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: >> * >> *

Audio System Property Keys
Property KeyInterface
>> + >> * >> * >> * >> --- 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: >> - *
int i = (int)(byte & 0xFF)
>> + *
{@code int i = (int)(byte & 0xFF)}
>> *

>> * 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: >> * >> *

MIDI File Format Properties
Property keyValue type
>> + * >> * >> * >> * >> @@ -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 InvalidMidiDataException if >> status does not >> + * @throws InvalidMidiDataException if status 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 InvalidMidiDataException 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 InvalidMidiDataException 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 InvalidMidiDataException if the >> + * @throws InvalidMidiDataException if the >> * status 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), false if the instrument could >> not be >> * loaded (for example, if the synthesizer has insufficient >> * memory to load it) >> - * @throws IllegalArgumentException if this >> + * @throws IllegalArgumentException if this >> * Synthesizer doesn't support the specified >> instrument's >> * soundbank >> * @see #unloadInstrument >> @@ -186,7 +186,7 @@ >> /** >> * Unloads a particular instrument. >> * @param instrument instrument to unload >> - * @throws IllegalArgumentException if this >> + * @throws IllegalArgumentException if this >> * Synthesizer 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 true if the instrument succeessfully >> remapped, >> * false if feature is not implemented by synthesizer >> - * @throws IllegalArgumentException if instrument >> + * @throws IllegalArgumentException if instrument >> * from or instrument to aren't >> supported by >> * synthesizer or if instrument to is not loaded >> - * @throws NullPointerException if >> from or >> + * @throws NullPointerException if from or >> * to 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 ArrayIndexOutOfBoundsException 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: >> * >> *
MIDI System Property Keys
Property KeyInterface
>> + * >> * >> * >> * >> --- 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: >> * >> *
Audio File Format Property Keys
Property keyValue type
>> + * >> * >> * >> * >> --- 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: >> * >> *
Audio Format Property Keys
Property keyValue type
>> + * >> * >> * >> * >> --- 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 true, or "false" or "off" for >> false. >> */ >> --- 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 @@ >> * DataLine. >> * >> * @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. From Sergey.Bylokhov at oracle.com Tue Aug 6 13:43:51 2013 From: Sergey.Bylokhov at oracle.com (Sergey Bylokhov) Date: Wed, 07 Aug 2013 00:43:51 +0400 Subject: RFR JDK 8 8022174 Fix doclint warnings in javax.sound In-Reply-To: <52015DE2.1080404@oracle.com> References: <52009654.9030509@oracle.com> <52015737.80506@oracle.com> <52015DE2.1080404@oracle.com> Message-ID: <52016007.30606@oracle.com> 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 data >>> * byte array >>> - * @throws InvalidMidiDataException 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: >>> * >>> - *
>>> + * 
{@code
>>>   * MidiDevice device = ...;
>>>   * if ( ! (device instanceof Sequencer) && ! (device instanceof 
>>> Synthesizer)) {
>>>   *   // we're now sure that device represents a MIDI port
>>>   *   // ...
>>>   * }
>>> - * 
>>> + * }
>>> * >>> *

>>> * A MidiDevice includes a {@link >>> MidiDevice.Info} 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: >>> * >>> *

Audio System Property Keys
Property KeyInterface
>>> + >>> * >>> * >>> * >>> --- 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: >>> - *
int i = (int)(byte & 0xFF)
>>> + *
{@code int i = (int)(byte & 0xFF)}
>>> *

>>> * 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: >>> * >>> *

MIDI File Format Properties
Property keyValue type
>>> + * >>> * >>> * >>> * >>> @@ -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 InvalidMidiDataException if >>> status does not >>> + * @throws InvalidMidiDataException if status >>> 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 InvalidMidiDataException 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 InvalidMidiDataException 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 InvalidMidiDataException if the >>> + * @throws InvalidMidiDataException if the >>> * status 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), false if the instrument >>> could not be >>> * loaded (for example, if the synthesizer has insufficient >>> * memory to load it) >>> - * @throws IllegalArgumentException if this >>> + * @throws IllegalArgumentException if this >>> * Synthesizer doesn't support the specified >>> instrument's >>> * soundbank >>> * @see #unloadInstrument >>> @@ -186,7 +186,7 @@ >>> /** >>> * Unloads a particular instrument. >>> * @param instrument instrument to unload >>> - * @throws IllegalArgumentException if this >>> + * @throws IllegalArgumentException if this >>> * Synthesizer 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 true if the instrument succeessfully >>> remapped, >>> * false if feature is not implemented by synthesizer >>> - * @throws IllegalArgumentException if instrument >>> + * @throws IllegalArgumentException if instrument >>> * from or instrument to aren't >>> supported by >>> * synthesizer or if instrument to is not loaded >>> - * @throws NullPointerException if >>> from or >>> + * @throws NullPointerException if from or >>> * to 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 ArrayIndexOutOfBoundsException 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: >>> * >>> *
MIDI System Property Keys
Property KeyInterface
>>> + * >>> * >>> * >>> * >>> --- 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: >>> * >>> *
Audio File Format Property Keys
Property keyValue type
>>> + * >>> * >>> * >>> * >>> --- 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: >>> * >>> *
Audio Format Property Keys
Property keyValue type
>>> + * >>> * >>> * >>> * >>> --- 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 true, or "false" or "off" for >>> false. >>> */ >>> --- 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 @@ >>> * DataLine. >>> * >>> * @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. From Sergey.Bylokhov at oracle.com Wed Aug 14 07:54:01 2013 From: Sergey.Bylokhov at oracle.com (Sergey Bylokhov) Date: Wed, 14 Aug 2013 18:54:01 +0400 Subject: [8] Request for review: 8023042 Inaccuracy in documentation in a sound area Message-ID: <520B9A09.9060302@oracle.com> Hello, Please review the fix for jdk 8. Text in the AudioFormat and AudioFileFormat was changed to the text from the MidiFileFormat. See also: http://mail.openjdk.java.net/pipermail/sound-dev/2013-August/000139.html Bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8023042 Webrev can be found at: http://cr.openjdk.java.net/~serb/8023042/webrev.00 -- Best regards, Sergey. From philip.race at oracle.com Fri Aug 30 10:32:26 2013 From: philip.race at oracle.com (Phil Race) Date: Fri, 30 Aug 2013 10:32:26 -0700 Subject: [8] Request for review: 8023042 Inaccuracy in documentation in a sound area In-Reply-To: <520B9A09.9060302@oracle.com> References: <520B9A09.9060302@oracle.com> Message-ID: <5220D72A.7090603@oracle.com> Got lost in my inbox. Looks fine. -phil. On 8/14/2013 7:54 AM, Sergey Bylokhov wrote: > Hello, > Please review the fix for jdk 8. > Text in the AudioFormat and AudioFileFormat was changed to the text > from the MidiFileFormat. > See also: > http://mail.openjdk.java.net/pipermail/sound-dev/2013-August/000139.html > > Bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8023042 > Webrev can be found at: > http://cr.openjdk.java.net/~serb/8023042/webrev.00 >
Audio System Property Keys
Property KeyInterface