RFR: 8343125: Correct the documentation for TreeMap's getFloorEntry and getCeilingEntry

[Chen Liang]

On Mon, 28 Oct 2024 06:05:50 GMT, Naman Nigam <duke at openjdk.org> wrote:

>> To get a JBS issue, please open a bug report about this typo in https://bugs.java.com/bugdatabase/. Also follow https://openjdk.org/guide for the rest of the steps for contributions.
>
>> To get a JBS issue, please open a bug report about this typo in https://bugs.java.com/bugdatabase/. Also follow https://openjdk.org/guide for the rest of the steps for contributions.
> 
> Thank you for your response @liach, I have
> - [x] filed the bug and referenced its ID
> - [x] signed the [OCA](https://oca.opensource.oracle.com/) and waiting for its approval
> 
> Please help me understand whom to add as a reviewer (and how) for such changes.

@namannigam Please take note of https://github.com/openjdk/jdk/pull/21729#issuecomment-2439595154

> Once you have signed the OCA, please let us know by writing `/signed` in a comment in this pull request.

You have filled in the issue ID correctly; but you need to make sure the PR title has the same text as the issue title. So the correct PR title will be

8343125: Correct the documentation for TreeMap's getFloorEntry and getCeilingEntry


For reviewers, this is the "JDK" project in the OpenJDK census: https://openjdk.org/census#jdk

People don't usually review until a patch (PR) is "rfr" (ready for review), which means that the oca has to be cleared first.

>> src/java.base/share/classes/java/util/TreeMap.java line 424:
>> 
>>> 422:     /**
>>> 423:      * Gets the entry corresponding to the specified key; returns the entry for
>>> 424:      * the least key greater than the specified key; if no such entry exists
>> 
>> What about: (same for the floor one)
>> 
>> Returns the entry for the least key greater than or equal to the specified key;
>> if no such entry exists (i.e. the specified key is greater than any key in the tree),
>> returns {@code null}.
>> 
>> What do you think of my version?
>
> Looks good to me and is similar to other methods of the form `get*` such as `getHigherEntry`. I could make that change and ensure documentation is similar for methods.

Indeed, ceil works like higher; given a key `k`, ceil allows exact `k` while higher does not, and they are otherwise the same. Same for floor/lower.

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

PR Comment: https://git.openjdk.org/jdk/pull/21729#issuecomment-2441925256
PR Review Comment: https://git.openjdk.org/jdk/pull/21729#discussion_r1821347656