<Sound Dev> <AWT Dev> [9] Review Request: 8050852 Javadoc cleanup of javax.sound.midi package

[Dan Rollo]

Hello Sergey,

Looks good to me. One comment below:

Is it considered good practice to “import” a class that is only referenced in javadoc? For example, your changes to src/share/classes/javax/sound/sampled/spi/AudioFileWriter.java add an import that is only used in javadoc. The prior version used a fully qualified reference in the javadoc, and avoided the import. 

{@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED… 
instead of:
{@link AudioSystem#NOT_SPECIFIED

I typically avoid such “unused imports” in order to avoid unintended coupling between classes and/or compilation issues. 

I saw this sort of “javadoc only import/unused import” in the following files:

src/share/classes/javax/sound/midi/MidiSystem.java
src/share/classes/javax/sound/midi/SoundbankResource.java
src/share/classes/javax/sound/midi/spi/SoundbankReader.java
src/share/classes/javax/sound/sampled/AudioSystem.java
src/share/classes/javax/sound/sampled/spi/AudioFileWriter.java


Best Regards,
Dan Rollo

On Jul 23, 2014, at 5:44 AM, Sergey Bylokhov <Sergey.Bylokhov at oracle.com> wrote:

> Hello,
> Any volunteers to be a second reviewer?
> 
> On 17.07.2014 12:18, Petr Pchelko wrote:
>> Hello, Sergey.
>> 
>> The fix looks good to me.
>> 
>> With best regards. Petr.
>> 
>> On 16 июля 2014 г., at 20:56, Sergey Bylokhov <Sergey.Bylokhov at oracle.com> wrote:
>> 
>>> Hello.
>>> Please review another one javadoc cleanup in jdk 9 in sound area:
>>> - @param, @return should not end with a dot, except a case when more than one sentences are used.
>>> - @param, @throws, @return now align, to be more readable.
>>> - @see tags simplified in some places.
>>> - Description of the class/method/field should be followed by dot.
>>> - Broken links/typos fixed
>>> - 80 column limit.
>>> - sets of spaces in the middle of text were deleted.
>>> - <tag> replaced by {@tag }.
>>> - unnecessary imports were removed.
>>> 
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8050852
>>> See the full specdiff: http://cr.openjdk.java.net/~serb/8050852/javadoc/overview-summary.html
>>> Webrev can be found at: http://cr.openjdk.java.net/~serb/8050852/webrev.02
>>> 
>>> -- 
>>> Best regards, Sergey.
>>> 
> 
> 
> -- 
> Best regards, Sergey.
>