<i18n dev> RFR: 8278254: Cleanup doclint warnings in java.desktop module [v2]

[Alexey Ivanov]

On Mon, 17 Jan 2022 05:31:00 GMT, Prasanta Sadhukhan <psadhukhan at openjdk.org> wrote:

>> The changes done under JDK-8278175 suppress on a per-file basis various missing comments that would otherwise trigger doclint warnings. Fixed them so as to remove the doclint:missing warnings.
>
> Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   review fix

Changes requested by aivanov (Reviewer).

src/java.desktop/share/classes/java/awt/BufferCapabilities.java line 67:

> 65:      * Returns the imaga capabilities of the front (displayed) buffer.
> 66:      *
> 67:      * @return the imaga capabilities of the front (displayed) buffer

Typo
Suggestion:

     * Returns the image capabilities of the front (displayed) buffer.
     *
     * @return the image capabilities of the front (displayed) buffer

src/java.desktop/share/classes/java/awt/BufferCapabilities.java line 75:

> 73:     /**
> 74:      * Returns the image capabilities of all back buffers (intermediate buffers
> 75:      * are considered back buffers)

Missing full stop.
Suggestion:

     * Returns the image capabilities of all back buffers (intermediate buffers
     * are considered back buffers).

src/java.desktop/share/classes/java/awt/BufferCapabilities.java line 85:

> 83: 
> 84:     /**
> 85:      * Returns whether or not the buffer strategy uses page flipping; a set of

I am for simplified form which implies the same:
Suggestion:

     * Returns whether the buffer strategy uses page flipping; a set of


Probably there should be full stop after “flipping”. Javadoc uses the first sentence to provide a short summary of the method description. Without the full stop, the description is overly detailed. What do you think?

src/java.desktop/share/classes/java/awt/BufferCapabilities.java line 92:

> 90:      * buffers uses blitting to copy the contents from one buffer to
> 91:      * another; when this is the case, {@code getFlipContents} returns
> 92:      * {@code null}

Suggestion:

     * {@code null}.

Full stop to end the sentence.

src/java.desktop/share/classes/java/awt/BufferCapabilities.java line 136:

> 134:      * Returns whether or not
> 135:      * page flipping can be performed using more than two buffers (one or more
> 136:      * intermediate buffers as well as the front and back buffer).

I'd rather re-flow both the description and `@return` tag description, the latter could omit the text in the parentheses.

src/java.desktop/share/classes/java/awt/Component.java line 4137:

> 4135:          * Gets direct access to the back buffer, as an image.
> 4136:          *
> 4137:          * @return direct access to the back buffer, as an image.

Suggestion:

         * Provides direct access to the back buffer as an image.
         *
         * @return direct access to the back buffer as an image.


The comma before “as” makes the description confusing.

src/java.desktop/share/classes/java/awt/event/KeyEvent.java line 653:

> 651:     /* For European keyboards */
> 652:     /**
> 653:      * Constant for the DEAD_GRAVE key.

A suggestion: use the key description rather than constant.
Suggestion:

     * Constant for the Dead Grave key.

This is more human-friendly in my opinion. The names of the keys could be found at [KeyEvent line 1591](https://github.com/openjdk/jdk/blob/765c414752076cdf5d893364fb648b478d97523f/src/java.desktop/share/classes/java/awt/event/KeyEvent.java#L1591). They're really key name with first letters capitalised and spaces instead of underscores.

src/java.desktop/share/classes/java/awt/event/KeyEvent.java line 779:

> 777: 
> 778:     /**
> 779:      * Constant for the BRACELEFT key.

Suggestion:

     * Constant for the "{" key.

src/java.desktop/share/classes/java/awt/event/KeyEvent.java line 785:

> 783: 
> 784:     /**
> 785:      * Constant for the BRACERIGHT key.

Suggestion:

     * Constant for the "}" key.

src/java.desktop/share/classes/java/awt/event/KeyEvent.java line 1018:

> 1016:     /* for Sun keyboards */
> 1017:     /**
> 1018:      * Constant for the "CUT" key.

I'd rather capitalise only the first letter of the key name.

src/java.desktop/share/classes/java/beans/beancontext/BeanContextServicesSupport.java line 161:

> 159:     /**
> 160:      * protected nested class containing per child information
> 161:      * in the "children" hashtable.

Suggestion:

     * A protected nested class containing per-child information
     * in the {@code children} hashtable.

src/java.desktop/share/classes/java/beans/beancontext/BeanContextServicesSupport.java line 794:

> 792: 
> 793:     /**
> 794:      * subclasses may subclass this nested class to represent proxy for

Suggestion:

     * Subclasses may subclass this nested class to represent a proxy for

src/java.desktop/share/classes/java/beans/beancontext/BeanContextSupport.java line 309:

> 307:     /**
> 308:      * protected nested class containing per child information
> 309:      * in the "children" hashtable.

Suggestion:

     * A protected nested class containing per-child information
     * in the {@code children} hashtable.

src/java.desktop/share/classes/javax/swing/JApplet.java line 109:

> 107:     /**
> 108:      * The <code>JRootPane</code> instance that manages the
> 109:      * <code>contentPane</code>

Suggestion:

     * <code>contentPane</code>.

src/java.desktop/share/classes/javax/swing/JDialog.java line 115:

> 113:     /**
> 114:      * The <code>JRootPane</code> instance that manages the
> 115:      * <code>contentPane</code>

Suggestion:

     * <code>contentPane</code>.

src/java.desktop/share/classes/javax/swing/JScrollBar.java line 111:

> 109: 
> 110:     /**
> 111:      * Orientation for this scrollBar

Suggestion:

     * Orientation of this scrollbar.

src/java.desktop/share/classes/javax/swing/JScrollBar.java line 120:

> 118:     /**
> 119:      * Amount to change the scrollbar's value by,
> 120:      * given a unit up/down request.

Suggestion:

     * The amount to change the value of the scrollbar by,
     * given a unit up/down request.

However, this still looks cumbersome and is not as clear.

src/java.desktop/share/classes/javax/swing/JScrollBar.java line 129:

> 127:     /**
> 128:      * Amount to change the scrollbar's value by,
> 129:      * given a block (usually "page") up/down request.

Suggestion:

     * The amount to change the value of the scrollbar by,
     * given a block (usually "page") up/down request.

src/java.desktop/share/classes/javax/swing/filechooser/FileSystemView.java line 353:

> 351:      * File(parent, fileName)</code> except when parent and child are both
> 352:      * special folders, in which case the <code>File</code> is a wrapper containing
> 353:      * a <code>ShellFolder</code> object.

Suggestion:

     * Returns a <code>File</code> object which is normally constructed with <code>new
     * File(parent, fileName)</code> except when the parent and child are both
     * special folders in which case the <code>File</code> is a wrapper containing
     * a <code>ShellFolder</code> object.

Does it make sense to simplify the description of `@return` tag?

src/java.desktop/share/classes/javax/swing/plaf/metal/MetalBorders.java line 928:

> 926: 
> 927:     /**
> 928:      * The class represents the border of a {@code JTextField}.

Suggestion:

     * Border for a {@code JTextField}.

Such a description is used for other classes which aren't public.

src/java.desktop/share/classes/javax/swing/plaf/metal/MetalBorders.java line 1029:

> 1027: 
> 1028:     /**
> 1029:      * The class represents the border of a {@code JToggleButton}.

Suggestion:

     * Border for a {@code JToggleButton}.

src/java.desktop/share/classes/javax/swing/text/LayeredHighlighter.java line 32:

> 30: /**
> 31:  * Highlighter interface to mark up the background of leaf views
> 32:  * with colored areas.

Suggestion:

 * Implementation of {@code Highlighter} interface to mark up the background of leaf views
 * with colored areas.

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java line 1686:

> 1684: 
> 1685:         /**
> 1686:          * Returns <code>HTMLDocument</code> of given <code>JEditorPane</code>.

Suggestion:

         * Returns <code>HTMLDocument</code> of the given <code>JEditorPane</code>.

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java line 1700:

> 1698: 
> 1699:         /**
> 1700:          * Returns HTMLEditorKit of given <code>JEditorPane</code>.

Suggestion:

         * Returns HTMLEditorKit of the given <code>JEditorPane</code>.

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java line 113:

> 111: 
> 112:     /**
> 113:      * Return the attribute name.

Suggestion:

     * Returns the attribute name.

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java line 122:

> 120: 
> 121:     /**
> 122:      * Return the attribute type.

Suggestion:

     * Returns the attribute type.

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java line 132:

> 130: 
> 131:     /**
> 132:      * Return attribute modifier.

Suggestion:

     * Returns the attribute modifier.

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java line 142:

> 140: 
> 141:     /**
> 142:      * Return possible attribute values.

Suggestion:

     * Returns possible attribute values.

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java line 151:

> 149: 
> 150:     /**
> 151:      * Return default attribute value.

Suggestion:

     * Returns the default attribute value.

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java line 160:

> 158: 
> 159:     /**
> 160:      * Return the next attribute in the list.

Suggestion:

     * Returns the next attribute in the list.

src/java.desktop/share/classes/javax/swing/undo/UndoableEditSupport.java line 150:

> 148: 
> 149:     /**
> 150:      * Start UndoableEdit.

Suggestion:

     * Starts a compound update.

-------------

PR: https://git.openjdk.java.net/jdk/pull/7004