On Mon, 17 Jan 2022 05:31:00 GMT, Prasanta Sadhukhan <psadhuk...@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
