RFR: 8310033: Clarify return value of Java Time compareTo methods [v3]

[Raffaello Giulietti]

On Wed, 21 Jun 2023 16:29:40 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> In java.time packages, clarify timeline order javadoc to mention "before" and "after" in the value of the `compareTo` method return values. 
>> Add javadoc @see tags to isBefore and isAfter methods
>> 
>> Replace use of "negative" and positive with "less than zero" and "greater than zero" in javadoc @return
>> The term "positive" is ambiguous, zero is considered positive and indicates equality.
>
> Roger Riggs has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Clarify return values of date time classes

Most modern authors in math topics use positive to mean > 0, negative to mean < 0, and 0 is neither.

In some contexts, like in the IEEE 754 standard for floating-point numbers, there are both distinguishable positive and a negative binary zeros. There's no "unsigned" or "agnostic" zero there.

The natural numbers include 0 in foundational topics like set theory (where 0 is _defined_ as the empty set), and exclude it in others.

BTW, [math.net](https://www.math.net/positive-numbers) contradicts itself later on the same page. In the "Is 0 positive or negative?" section it states "Positive numbers are defined as any number that is greater than zero".

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

PR Comment: https://git.openjdk.org/jdk/pull/14479#issuecomment-1609970331