RFR: 8282473: Refactor swing classes javadoc to use @throws instead of @exception

[Alexey Ivanov]

On Tue, 1 Mar 2022 10:16:16 GMT, Prasanta Sadhukhan <psadhukhan at openjdk.org> wrote:

> Prevailing JDK coding practices use "@throws" rather than "@exception".
> Refactor existing swing classes javadoc to use @throws

Marked as reviewed by aivanov (Reviewer).

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

> 137:      *
> 138:      * @throws HeadlessException if GraphicsEnvironment.isHeadless()
> 139:      * returns true.

Suggestion:

     * returns true

In other cases, there's no ending punctuation for `@throws`.

src/java.desktop/share/classes/javax/swing/JColorChooser.java line 154:

> 152:      * @return the selected color or <code>null</code> if the user opted out
> 153:      * @throws HeadlessException if GraphicsEnvironment.isHeadless()
> 154:      * returns true.

It looks `HeadlessException` has the period everywhere where it's documented. In this case, I suggest addressing this under another issue.

src/java.desktop/share/classes/javax/swing/JLabel.java line 625:

> 623:      * @return the key value if {@code key} is a legal value for the
> 624:      *         verticalAlignment or verticalTextPosition properties
> 625:      * @throws IllegalArgumentException if key isn't TOP, CENTER, or BOTTOM.

Another case with ending punctuation.

src/java.desktop/share/classes/javax/swing/JRootPane.java line 582:

> 580:      * @param content the <code>Container</code> to use for component-contents
> 581:      * @throws java.awt.IllegalComponentStateException (a runtime
> 582:      *            exception) if the content pane parameter is <code>null</code>

Shall we remove _“(a runtime exception)”_ note?

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

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