RFR: 8272779: Package docs for javafx.embed.swing are misleading [v2]

Tue Aug 24 12:15:26 UTC 2021

On Tue, 24 Aug 2021 05:51:51 GMT, Prasanta Sadhukhan <psadhukhan at openjdk.org> wrote:

>> The API docs for the javafx.embed.swing package are misleading in that they only talk about the JFXPanel capability (embedding a JavaFX Scene in a Swing JComponent) and ignore the SwingNode functionality entirely. 
>> Fix the package doc.
>
> Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix

Looks pretty good with a few comments.

modules/javafx.swing/src/main/java/javafx/embed/swing/package.html line 39:

> 37: 
> 38: <body>
> 39: <p>Provides the set of classes to use JavaFX inside Swing applications.</p>

Unless you also remove this initial sentence, the docs are still misleading, since only the first sentence shows up in the module summary for a package.

modules/javafx.swing/src/main/java/javafx/embed/swing/package.html line 51:

> 49:    The {@link javafx.embed.swing.SwingNode} class is used to embed
> 50:    a Swing content into a JavaFX application.
> 51:    The content to be displayed is specified with the SwingNode.setContent method

`SwingNode.setContent` should either use `{@link ...}` or `{@code ...}`

modules/javafx.swing/src/main/java/javafx/embed/swing/package.html line 52:

> 50:    a Swing content into a JavaFX application.
> 51:    The content to be displayed is specified with the SwingNode.setContent method
> 52:    that accepts an instance of Swing {@code JComponent}. The hierarchy of components

instance of _a_ Swing ...

modules/javafx.swing/src/main/java/javafx/embed/swing/package.html line 56:

> 54:    components, otherwise {@code SwingNode} may fail to paint it. The content gets
> 55:    repainted automatically. All the input and focus events are forwarded to the
> 56:    {@code JComponent} instance transparently to the developer.</p>

I might suggest removing the "transparently to the developer" part of this from the package description, since you don't also say that for `JFXPanel`, and someone might wonder whether there is something they need to do in the `JFXPanel` case. Both of the class descriptions include this language, so I think that's sufficient.

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

PR: https://git.openjdk.java.net/jfx/pull/609