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

[Sergey Bylokhov]

Hi, Dan.
Yes, the links were changed intentionally to make readability of javadoc 
better, split of links across a few lines looks bad.

On 23.07.2014 20:51, Dan Rollo wrote:
> 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.
>>


-- 
Best regards, Sergey.