RFR: 6201035: Document NPE for passing null insets to constructors and methods of several javax.swing.border.* classes [v5]

[Alexey Ivanov]

On Mon, 31 Oct 2022 07:48:38 GMT, Prasanta Sadhukhan <psadhukhan at openjdk.org> wrote:

>> The behavior of MatteBorder constructors taking Insets object as a parameter is undocumented. It would throw NPE if null object is passed to it, which should be documented in the spec.
>
> Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Rectify javadoc of more border classes/methods

`TitledBorder` is to be updates as well.

I wonder why none of the classes uses `{@inheritDoc}` instead of copying the entire text without modification. And you don't want to use `{@inheritDoc}` either for the `@throws` clause without explaining why.

src/java.desktop/share/classes/javax/swing/border/AbstractBorder.java line 87:

> 85:      * @param c the component for which this border insets value applies
> 86:      * @param insets the object to be reinitialized
> 87:      * @return the <code>insets</code> object

Suggestion:

     * @return the {@code insets} object

It makes sense to replace `<code>` with `{@code}` as the `throws` clause uses the new syntax.

src/java.desktop/share/classes/javax/swing/border/BevelBorder.java line 142:

> 140: 
> 141:     /**
> 142:      * Reinitialize the insets parameter with this Border's current Insets.

To be consistent with the superclass:
Suggestion:

     * Reinitializes the insets parameter with this Border's current Insets.


I guess the entire javadoc can be inherited with {@inheritDoc}, it adds nothing to the text in `AbstractBorder`.

src/java.desktop/share/classes/javax/swing/border/CompoundBorder.java line 137:

> 135: 
> 136:     /**
> 137:      * Reinitialize the insets parameter with this Border's current Insets.

Suggestion:

     * Reinitializes the insets parameter with this Border's current Insets.

The same: the verb at start of a javadoc is in third person singular.

src/java.desktop/share/classes/javax/swing/border/EmptyBorder.java line 104:

> 102: 
> 103:     /**
> 104:      * Reinitialize the insets parameter with this Border's current Insets.

Suggestion:

     * Reinitializes the insets parameter with this Border's current Insets.

src/java.desktop/share/classes/javax/swing/border/EtchedBorder.java line 210:

> 208:     /**
> 209:      * Reinitialize the insets parameter with this Border's current Insets.
> 210:      *

Also add _“-s”_ ending to the verb in the line above.

src/java.desktop/share/classes/javax/swing/border/LineBorder.java line 174:

> 172:     /**
> 173:      * Reinitialize the insets parameter with this Border's current Insets.
> 174:      *

Also add _“-s”_ ending to the verb in the line above.

src/java.desktop/share/classes/javax/swing/border/SoftBevelBorder.java line 152:

> 150: 
> 151:     /**
> 152:      * Reinitialize the insets parameter with this Border's current Insets.

Suggestion:

     * Reinitializes the insets parameter with this Border's current Insets.

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

Changes requested by aivanov (Reviewer).

PR: https://git.openjdk.org/jdk/pull/10740