Fix Javadoc issues per Oracle conventions

[elharo]

No description provided.

[garydgregory]

-1: Sentences end in a period. This matters even more when there is more than one sentence in a description. The first sentence ends in a period but the second wouldn't? That makes no sense and looks like a typos to boot.
This is the convention I've been using all over Commons.

[elharo]

-1: Sentences end in a period. This matters even more when there is more than one sentence in a description. The first sentence ends in a period but the second wouldn't? That makes no sense and looks like a typos to boot. This is the convention I've been using all over Commons.

Sentences end in a period. Sentence fragments do not end in a period. This change does not make second sentence not end in a period (or if it does that's a bug)

[garydgregory]

It's just simpler to end in a period, whether there is one sentence or two.

The subtle differences Oracle tries to make are, IMO, absurd, for example, these examples where 3 out of 4 descripions end in a period:

When writing a phrase, do not capitalize and do not end with a period:
@param x the x-coordinate, measured in pixels

When writing a phrase followed by a sentence, do not capitalize the phrase, but end it with a period to distinguish it > from the start of the next sentence:
@param x the x-coordinate. Measured in pixels.

If you prefer starting with a sentence, capitalize it and end it with a period:
@param x Specifies the x-coordinate, measured in pixels.

When writing multiple sentences, follow normal sentence rules:
@param x Specifies the x-coordinate. Measured in pixels.

You can just end with a period and keep it simple. There’s no advantage to making this distinction, especially for non-native English speakers.

There is no "Sentence fragments".

[elharo]

sentence fragments == phrases.

These are subtle and picky, which is why iut;'s helpful to use an automated tool to take care of it instead of trying to remember the rules and nit picking on every PR