8022174: Fix doclint warnings in javax.sound
8022404: Fix doclint issues in java.applet
Reviewed-by: prr
--- a/jdk/src/share/classes/java/applet/AppletContext.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/java/applet/AppletContext.java Tue Aug 06 13:25:04 2013 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 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
@@ -56,7 +56,7 @@
/**
* Returns an <code>Image</code> object that can then be painted on
- * the screen. The <code>url</code> argument<code> </code>that is
+ * the screen. The <code>url</code> argument that is
* passed as an argument must specify an absolute URL.
* <p>
* This method always returns immediately, whether or not the image
@@ -157,7 +157,7 @@
* @param stream stream to be associated with the specified key. If this
* parameter is <code>null</code>, the specified key is removed
* in this applet context.
- * @throws <code>IOException</code> if the stream size exceeds a certain
+ * @throws IOException if the stream size exceeds a certain
* size limit. Size limit is decided by the implementor of this
* interface.
* @since 1.4
--- a/jdk/src/share/classes/javax/sound/midi/MetaMessage.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MetaMessage.java Tue Aug 06 13:25:04 2013 -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 {
--- a/jdk/src/share/classes/javax/sound/midi/MidiDevice.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MidiDevice.java Tue Aug 06 13:25:04 2013 -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
--- a/jdk/src/share/classes/javax/sound/midi/MidiDeviceReceiver.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MidiDeviceReceiver.java Tue Aug 06 13:25:04 2013 -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();
}
--- a/jdk/src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Tue Aug 06 13:25:04 2013 -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();
}
--- a/jdk/src/share/classes/javax/sound/midi/MidiFileFormat.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MidiFileFormat.java Tue Aug 06 13:25:04 2013 -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>
--- a/jdk/src/share/classes/javax/sound/midi/MidiMessage.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MidiMessage.java Tue Aug 06 13:25:04 2013 -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)) {
--- a/jdk/src/share/classes/javax/sound/midi/MidiSystem.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/MidiSystem.java Tue Aug 06 13:25:04 2013 -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,
--- a/jdk/src/share/classes/javax/sound/midi/ShortMessage.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/ShortMessage.java Tue Aug 06 13:25:04 2013 -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
*/
--- a/jdk/src/share/classes/javax/sound/midi/Synthesizer.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/Synthesizer.java Tue Aug 06 13:25:04 2013 -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
--- a/jdk/src/share/classes/javax/sound/midi/SysexMessage.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/SysexMessage.java Tue Aug 06 13:25:04 2013 -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) ) {
--- a/jdk/src/share/classes/javax/sound/midi/Track.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/midi/Track.java Tue Aug 06 13:25:04 2013 -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 {
--- a/jdk/src/share/classes/javax/sound/sampled/AudioFileFormat.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/sampled/AudioFileFormat.java Tue Aug 06 13:25:04 2013 -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>
--- a/jdk/src/share/classes/javax/sound/sampled/AudioFormat.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/sampled/AudioFormat.java Tue Aug 06 13:25:04 2013 -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>
--- a/jdk/src/share/classes/javax/sound/sampled/AudioSystem.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/sampled/AudioSystem.java Tue Aug 06 13:25:04 2013 -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>
--- a/jdk/src/share/classes/javax/sound/sampled/BooleanControl.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/sampled/BooleanControl.java Tue Aug 06 13:25:04 2013 -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>.
*/
--- a/jdk/src/share/classes/javax/sound/sampled/Mixer.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/sampled/Mixer.java Tue Aug 06 13:25:04 2013 -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
--- a/jdk/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java Tue Aug 06 18:54:02 2013 +0200
+++ b/jdk/src/share/classes/javax/sound/sampled/spi/FormatConversionProvider.java Tue Aug 06 13:25:04 2013 -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);