RFR: 6955128: Spec for javax.swing.plaf.basic.BasicTextUI.getVisibleEditorRect contains inappropriate wording [v2]

[Alexey Ivanov]

On Wed, 25 Jun 2025 10:36:46 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

>> src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTextUI.java line 1034:
>> 
>>> 1032:      * Gets the allocation for the root view.
>>> 1033:      * The returned rectangle is unrelated to visibility,
>>> 1034:      * and is used to set the size of the root view.
>> 
>> Suggestion:
>> 
>>      * The returned rectangle is unrelated to visibility.
>>      * It is used to set the size of the root view.
>> 
>> I still think, “it is used…” is clearer.
>
> We may break the description into paragraphs like this:
> 
> 
>     /**
>      * Gets the allocation for the root view.
>      * <p>
>      * The returned rectangle is unrelated to visibility.
>      * It is used to set the size of the root view.
>      * <p>
>      * The component must have a non-zero positive size for
>      * this translation to be computed.
>      *
>      * @return the bounding box for the root view
>      *
>      * @see View#paint
>      * @see View#setSize
>      */
>     protected Rectangle getVisibleEditorRect() {
> 
> This way different parts of the description are clearly separated, therefore each part stands out when one scans the javadoc for information.

If linked with ‘and’, there should be no comma.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25850#discussion_r2166414060