[OpenJDK 2D-Dev] [10] Review Request: 8184435 Cleanup of javadoc in javax.print package

[Sergey Bylokhov]

Hi, Prasanta.
Thank you for review!

The new version:
http://cr.openjdk.java.net/~serb/8184435/webrev.08/
webrev diff v07 vs v08:
http://cr.openjdk.java.net/~serb/8184435/webrev.08/v7_v8.diff

See comments inline.

On 07.08.2017 3:29, Prasanta Sadhukhan wrote:
> Hi Sergey, javax/print/Doc.java 52 * {@link javax.print.attribute} 
> should be {@link javax.print.attribute javax.print.attribute}, I guess

Both versions generate the same html links so the second part is not 
necessary.

> 
> 83  * interface Doc should be interface {@code Doc}

Fixed.

> 
> javax/print/DocFlavor.ja >
> 347 * {@link java.awt.datatransfer.DataFlavor}. should be {@link 
> java.awt.datatransfer.DataFlavor DataFlavor}

The full name is used to highlight that DataFlavor class located in 
other package and it should not be confused with DocFlavor.


437 * @throws
> NullPointerException if {@code mimeType} or {@code className} are should 
> be "is"

Fixed.

> 
>   
> 31 * condition involving a doc flavor or flavors (class {@link 
> DocFlavor} same as line 347 javax/print/MimeType.java Javadoc is added 
> for this method. Why something similar is not added for other public 
> methods? 124 /**
> 125 * Constructs a new parameter map entry.
> 126 *

Most of other methods in this and some other classes have a spec from 
the parent class.

> javax/print/MultiDocPrintService.java 31 * capabilities of a 
> {@code Printer} should not use {@code Printer} as it is not a class. 
> javax/print/PrintService.java 36 * {@code PrintService} describes the 
> capabilities of a {@code Printer} .....same as previous

Fixed.

> javax/print/PrintServiceLookup.java it's a private method. Do we need 
> this javadoc? 454 /**
> 455 * Locates {@code MultiDoc} print {@code Services} capable of printing
> 456 * {@code MultiDocs} containing all the specified doc flavors.

I added a specs to some private fields/methods , so at some point we 
will be able to enable doclint for everything.

> 457 * javax/print/ServiceUI.java 147 * attributes is {@code null}, or 
> the initial PrintService should have {@code PrintService} 
> javax/print/StreamPrintService.java 47 * output in a format useful in 
> other contexts. StreamPrintService's should have {@code 
> StreamPrintService} This is what I have looked so far.

Fixed.

> 
> Regards
> Prasanta
> On 7/17/2017 5:12 AM, Sergey Bylokhov wrote:
>> Hello,
>> Please review the fix for jdk10.
>> The cleanup was done in the same way as for datatransfer, sound and 
>> accessibility packages(see links in the CR).
>>
>> I suggest to check the specdiff first, because for some methods the 
>> specification was reworked. CSR will be filed after technical review.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8184435
>> Webrev can be found at: 
>> http://cr.openjdk.java.net/~serb/8184435/webrev.07
>> Specdiff: 
>> http://cr.openjdk.java.net/~serb/8184435/specdiff.07/overview-summary.html
>>
>> In this fix the javadoc is updated and the next rules were applied:
>>  - <tag> should be replaced by {@tag }
>>  - 80 column limit
>>  - description of the class/method/field should be followed by dot
>>  - @param, @return should not end with a dot, except a case when more 
>> than one sentences are used
>>  - empty line after description/before the first tag was added
>>  - unnecessary empty lines were removed
>>  - sets of spaces in the middle of text were deleted
>>  - @param, @throws, @return should be aligned, to be more readable
>>  - unnecessary imports should be removed
>>  - the "null"/"true"/"false"/"this"/"ClassName" should be wrapped in 
>> {@code } when necessary
>>  - the order of different tags were unified across the package
>> ... etc
>>
>> There are also some mixing of different "reference usage", for example 
>> "InputStream" vs "input stream", "String" vs "string", etc. I tried to 
>> fix some of them.
>>
> 


-- 
Best regards, Sergey.