RFR: 8278254: Cleanup doclint warnings in java.desktop module

[Sergey Bylokhov]

On Mon, 10 Jan 2022 05:25:51 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.

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

> 63: 
> 64:     /**
> 65:      * Returns the imaga capabilities of the front buffer

Please add a dot after the first sentence, it is used as a summary doc for the method.
Why the text about "displayed" buffer is removed? is it some special "term" like "intermediate" below?

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

> 132: 
> 133:     /**
> 134:      * Returns whether or not

I am not sure that preserving such a format style is a good thing.

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

> 4695: 
> 4696:     /**
> 4697:      * Checks whether or not paint messages received from the operating system

In the change above the "Returns whether or not" text is used. It is better to use the same new text, or just use the old one.

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

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

I do not know, are all the keys here actually "function keys"?

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

> 148:     /************************************************************************/
> 149: 
> 150:     /**

This will add many statements to the specification which could be verified by the TCK. DO we really want to say all of that? Especially about serialization. Same question for other changes below.

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

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

Should we wrap the HTMLDocument by the <code>?

src/java.desktop/share/classes/javax/swing/text/html/parser/Parser.java line 213:

> 211: 
> 212:     /**
> 213:      * Return the line number of the line currently being parsed.

In some other places above the "Returns xxx" was used.

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

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

What does it mean? Is it clear enough for the class which "managing <code>UndoableEdit</code> listeners"?

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

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