[10] Review Request: 8184435 Cleanup of javadoc in javax.print package

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[10] Review Request: 8184435 Cleanup of javadoc in javax.print package

Sergey Bylokhov
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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [10] Review Request: 8184435 Cleanup of javadoc in javax.print package

Sergey Bylokhov
Any volunteers? =)

On 16.07.2017 16:42, 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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [10] Review Request: 8184435 Cleanup of javadoc in javax.print package

prasanta sadhukhan
In reply to this post by Sergey Bylokhov
Hi Sergey,

javax/print/Doc.java
52  *   {@link javax.print.attribute} should be {@link javax.print.attribute javax.print.attribute}, I guess
83  * interface Doc should be interface {@code Doc}

javax/print/DocFlavor.java

347  * {@link java.awt.datatransfer.DataFlavor}. should be {@link java.awt.datatransfer.DataFlavor DataFlavor}

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

 
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          *

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 

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


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [10] Review Request: 8184435 Cleanup of javadoc in javax.print package

prasanta sadhukhan

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.





Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [10] Review Request: 8184435 Cleanup of javadoc in javax.print package

Sergey Bylokhov
On 13.08.2017 23:23, Prasanta Sadhukhan wrote:
> 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).

The second part is needed(at least we use it) when the class name is
used, but "{@link javax.print.attribute}" is a package.

If there are no more objections from others I'll create a CSR based on
this webrev.

--
Best regards, Sergey.
Loading...