On Wed, 25 Jun 2025 07:06:13 GMT, Prasanta Sadhukhan <psadhuk...@openjdk.org>
wrote:
>>> It is passed to `View.setSize` also so just mentioning one may not be right…
>>
>> Right. Both uses cases fall into the same category: the allocation controls
>> the size of the root view.
>>
>> The returned allocation rectangle is also used in handling mutations to the
>> text model.
>>
>> I'd rather leave it without any explanation why it's called *allocation*.
>> Anyone who dealt with Swing text components and their implementation of the
>> view classes is expected to roughly understand what allocation means.
>> Searching for usages of `getVisibleEditorRect` reveals the usages.
>>
>>> `{@code allocation}` is a no-op as it is not a class..
>>
>> Yes, it is an op: it refers to `allocation` the parameter of the `paint`
>> method.
>>
>>> Maybe we can mention "The returned rectangle is unrelated to visibility,
>>> and is used as an allocation parameter in javax.swing.text.View class to
>>> set the size and paint the allocated View"
>>
>> If we stick to explaining *allocation*, your suggestion makes sense, I
>> edited it a bit: _“The returned rectangle is unrelated to visibility, it is
>> used to set the size of the root view.”_ This is what it means… without
>> going too deep into the details.
>>
>> We could add `@see` links for `View.paint` and/or `View.setSize`, the link
>> to paint could be the most useful because it has a parameter called
>> `allocation`.
>
> Updated javadoc.
> @prrace Can you please take a look? CSR will be required?
My take is that CSR isn't required because the meaning remains the same.
However, the added clarification may still be documented with a CSR.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/25850#discussion_r2166925446
