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

[Artem Ananiev]

Hi, Sergey,

I spotted a few differences, but I don't have a strong opinion whether 
they should be fixed. Leaving them up to you.

In other words, I'm fine with the fix.

Thanks,

Artem

On 3/21/2014 3:47 PM, Sergey Bylokhov wrote:
> On 3/21/14 3:17 PM, Artem Ananiev wrote:
>> Hi, Sergey,
>>
>> it looks fine.
>>
>> Have you verified that
>>
>> @see InputStream#mark
>>
>> is resolved by JavaDoc to the correct link? Shouldn't it be
>>
>> @see java.io.InputStream#mark
>>
>> ?
> Yes. it is ok as before:
> http://download.java.net/jdk8/docs/api/javax/sound/midi/spi/MidiFileReader.html
>>
>> MidiFileWriter: class JavaDoc contains both {@code} and {@link}, do we
>> need to use one of them? Other classes contain {@code} only and don't
>> use {@link}.
> Actually some  classes use {@code} some {@link}. I can change them to
> use @link on the first reference to a specific class and @code for
> subsequent references.
> http://download.java.net/jdk8/docs/api/javax/sound/midi/spi/MidiFileWriter.html
>>
>> MidiFileWriter: some params are described as
>>
>> @param sequence the sequence for which ...
>>
>> while MidiFileReader uses different syntax:
>>
>> @return a {@code Sequence} object ...
> these are a different tags, return has no name and it use type, and
> parameter has name and it is used.
>>
>> MidiFileWriter.write(): signature contains "throws IOException" only,
>> while JavaDoc also says about IllegalArgumentException.
> I guess this is ok, since this is a part of specification and
> IllegalArgumentException is a RuntimeException.
>>
>> SoundbankReader: the same comment about {@code} and {@link} as above.
>>
>> Thanks,
>>
>> Artem
>>
>> On 3/21/2014 3:01 PM, Sergey Bylokhov wrote:
>>> Any volunteers?
>>>
>>> On 3/15/14 7:07 PM, Sergey Bylokhov wrote:
>>>> Hello.
>>>> Please review a javadoc "weekend cleanup" in jdk 9.
>>>>  - 80 column limit
>>>>  - <tags> replaced to @tags
>>>>  - empty line after description/before the first tag
>>>>  - @param, @throws, @return now align, to be more readable
>>>>
>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8037117
>>>> Webrev can be found at:
>>>> http://cr.openjdk.java.net/~serb/8037117/webrev.01/
>>>>
>>>
>>>
>
>
> --
> Best regards, Sergey.
>