On Period and DateTimeFormatter

[Pavel Rappo]

Hello, I have two questions on java.time API.

The first one is about documentation for java.time.Period. When I get
back to the API after a long period (no pun intended) of not using it,
it takes me a while to recall that Period does __NOT__ model an
interval between two specific points in time, such as vacation dates.
And the signature of the Period.between(LocalDate, LocalDate) method
makes it even harder.

I'm not sure what it is. Is it because I'm a non-native English
speaker or it's some idiosyncrasy? Anyway, if it's not just me, then
my question is: would it make sense to provide a few short and punchy
notes to the reader to quickly rectify this misconception that might
be forming in their head while they are reading the documentation?
Sometimes it's helpful to say what something isn't in addition to
saying what something is.


The second question is about DateTimeFormatter. I recently had to
parse a date that resembles output of asctime: Sat Jul 16 02:03:55
+0000 1994. It's fine and dandy until you parse a date in September.
That time format expects "Sep", while the formatter expects "Sept".

Now, I'm aware that it's a known issue [^1]. Still, I wonder if we can
do anything better than suggest using a specific locale, which is not
bulletproof, or going to the DateTimeFormatterBuilder route.

Thanks,
-Pavel

[^1]: See https://bugs.openjdk.org/browse/JDK-8256837 and its numerous
duplicates.