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

[Alexey Ivanov]

On Fri, 4 Jul 2025 03:09:32 GMT, Prasanta Sadhukhan <psadhukhan at openjdk.org> wrote:

>> BasicTextUI.getVisibleEditorRect wording is rephrased to remove the wording "Due to an unfortunate set of historical events this method is inappropriately named".
>
> Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update javadoc

Changes requested by aivanov (Reviewer).

src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTextUI.java line 1032:

> 1030: 
> 1031:     /**
> 1032:      * Gets the allocation (i.e. the allocated size) for the root view.

> What I've been asking for is something like\
> "Gets the allocation (i.e. the allocated size) for the root view."

"Gets the allocation (i.e. the size) for the root view."

@prrace Does it sound better?

The [style guide](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#styleguide) for writing javadoc says:

> **Avoid Latin**
> 
> use "also known as" instead of "aka", use "that is" or "to be specific" instead of "i.e.", use "for example" instead of "e.g.", and use "in other words" or "namely" instead of "viz."

Taking the style guide into account, the text should change to

Suggestion:

     * Gets the allocation (that is the allocated size) for the root view.


I still don't like repeating _“allocated”_, does it clarify the meaning of just _“the size”_?

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

PR Review: https://git.openjdk.org/jdk/pull/25850#pullrequestreview-2986680868
PR Review Comment: https://git.openjdk.org/jdk/pull/25850#discussion_r2185065187