RFR: 4622866: javax.swing.text.Document.remove(int, int) has a misleading picture

[Alexey Ivanov]

On Wed, 13 Sep 2023 07:46:50 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

> The image in the [documentation for `Document.remove`](https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/swing/text/Document.html#remove(int,int)) looks as if the portion between the offsets 6 and 10 is removed. However, the entire region for _‘quick ’_ is highlighted.
> 
> I updated the image to mark the start offset 4 and the end offset 10. The new image is in SVG format which looks crisp on modern High DPI displays.
> 
> I added a sentence that describes the image, which makes the documentation accessible and clearer.
> 
> Also, I marked up references to classes and members with `{@code}`.
> 
> Look at the updated version: [`Document.remove` in JDK 22](https://cr.openjdk.org/~aivanov/4622866/api/java.desktop/javax/swing/text/Document.html#remove(int,int)).

Perhaps, the intention of the original image was to demonstrate that all the marks in the range 4–10 are collapsed to 4. That is the mark at offset 6 is at offset 4 after the removal:

![Diagram of removal of ‘quick’ from ‘The quick brown fox.’ The marks at offsets 4, 6, 10 have offset 4 after the removal](https://cr.openjdk.org/~aivanov/4622866/Document-remove-with-6-crisp4.svg)

The above image could still be confusing.

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

PR Comment: https://git.openjdk.org/jdk/pull/15701#issuecomment-1717171413