[OpenJDK 2D-Dev] [12] Review Request: 8212790 Javadoc cleanup of java.awt.color package

[Phil Race]

On 10/29/18 12:53 PM, Sergey Bylokhov wrote:
> Hi, Phil.
> See my comments inline:
>
> On 27/10/2018 13:02, Philip Race wrote:
>> I am wondering why you took out the unordered list here :
>> https://docs.oracle.com/javase/9/docs/api/java/awt/color/ICC_ProfileRGB.html 
>>
>>
>> The specdiff *maybe* doesn't really tell me what it looks like now 
>> but I don't see how
>> it can still be a list ...
>
> I have changed it from the list to the plain text(this text is similar 
> as in ICC_ProfileGray), the reason is that the first sentence in the 
> class description is used as a summary of the class in the package 
> javadoc:
> https://docs.oracle.com/javase/9/docs/api/java/awt/color/package-summary.html 
>

I see. OK. Approved.

-phil.

>
> And before the fix it was appeared as a plain text(w/o list). So I 
> unified it for all places:
> http://cr.openjdk.java.net/~serb/8212790/specdiff.00/java.desktop/java/awt/color/package-summary.html 
>
>
>>
>> May I assume you tested out any newly added links ?
>> eg
>>
>> 73 * spaces via {@link ColorSpace#getInstance}.
>
> yes.
>
>>
>> Looks straightforward so I don't expect any issues, just checking.
>>
>> Also it looks as if some lines got longer due to reformatting, are 
>> they are still within bounds ?
>
> Correct, this is one of the goal of the fix.
>
>>
>> eg
>>
>> - *
>> - * A subclass of the ICC_Profile class which represents profiles
>> - * which meet the following criteria: the color space type of the
>> - * profile is TYPE_GRAY and the profile includes the grayTRCTag and
>> - * mediaWhitePointTag tags. Examples of this kind of profile are
>> - * monochrome input profiles, monochrome display profiles, and
>> - * monochrome output profiles. The getInstance methods in the
>> - * ICC_Profile class will
>> - * return an ICC_ProfileGray object when the above conditions are
>> - * met. The advantage of this class is that it provides a lookup
>> - * table that Java or native methods may be able to use directly to
>> - * optimize color conversion in some cases.
>> + * The {@code ICC_ProfileGray} class is a subclass of the {@code 
>> ICC_Profile}
>> + * class that represents profiles which meet the following criteria: 
>> the color
>> + * space type of the profile is {@code TYPE_GRAY} and the profile 
>> includes the
>> + * {@code grayTRCTag} and {@code mediaWhitePointTag} tags. The
>> + * {@code getInstance} methods in the {@code ICC_Profile} class will 
>> return an
>> + * {@code ICC_ProfileGray} object when the above conditions are met. 
>> Examples of
>> + * this kind of profile are monochrome input profiles, monochrome 
>> display
>> + * profiles, and monochrome output profiles.
>> + * <p>
>> + * The advantage of this class is that it provides a lookup table 
>> that Java
>> + * or native methods can use directly to optimize color conversion 
>> in some
>> + * cases.
>>
>>
>> -phil
>>
>> On 10/24/18, 9:36 PM, Sergey Bylokhov wrote:
>>> Hi, Krishna.
>>> Thank you for review!
>>>
>>>> 1894, 1895, 1902, 1904.
>>> The text on the lines above is a block comment not a javadoc, the 
>>> tags are not necessary there.
>>>
>>>> 1570, 1601, 
>>>
>>> I have fixed these:
>>> http://cr.openjdk.java.net/~serb/8212790/webrev.01
>>>
>
>