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

[Sergey Bylokhov]

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

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
>>


-- 
Best regards, Sergey.