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

Prasanta Sadhukhan prasanta.sadhukhan at oracle.com
Mon Aug 14 06:23:54 UTC 2017


Hi Sergey,


On 8/12/2017 5:38 AM, Sergey Bylokhov wrote:
> 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.
>
In that case, will this be required to have 2nd part?

43 * {@link DocFlavor DocFlavor}
There are manyof them in other files too like DocFlavor.java
1206 * stream ({@link java.io.Reader java.io.Reader} Other than that, it 
looks ok to me (btw, I have not gone through each and every file). 
Regards Prasanta

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/2d-dev/attachments/20170814/fc6084ce/attachment.html>


More information about the 2d-dev mailing list