8068284: Missing @throws in DateTimeFormatterBuilder.appendOffset

8068285: Missing @throws in DateTimeFormatterBuilder.appendInstant
8062803: 'principal' should be 'principle' in java.time package description
8062796: java.time.format.DateTimeFormatter error in API doc example

Reviewed-by: lancea, mchung

jdk/src/java.base/share/classes/java/time/format/DateTimeFormatter.java

@@ -117,8 +117,9 @@ import java.util.Set;
  * {@code parse(CharSequence text, DateTimeFormatter formatter)}.
  * <p>For example:
  * <blockquote><pre>
+ *  LocalDate date = LocalDate.now();
  *  String text = date.format(formatter);
- *  LocalDate date = LocalDate.parse(text, formatter);
+ *  LocalDate parsedDate = LocalDate.parse(text, formatter);
  * </pre></blockquote>
  * <p>
  * In addition to the format, formatters can be created with desired Locale,
@@ -265,9 +266,10 @@ import java.util.Set;
  * <p>
  * For example:
  * <blockquote><pre>
+ *  LocalDate date = LocalDate.now();
  *  DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
  *  String text = date.format(formatter);
- *  LocalDate date = LocalDate.parse(text, formatter);
+ *  LocalDate parsedDate = LocalDate.parse(text, formatter);
  * </pre></blockquote>
  * <p>
  * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The

jdk/src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java

@@ -849,6 +849,7 @@ public final class DateTimeFormatterBuilder {
      * @param fractionalDigits  the number of fractional second digits to format with,
      *  from 0 to 9, or -1 to use as many digits as necessary
      * @return this, for chaining, not null
+     * @throws IllegalArgumentException if the number of fractional digits is invalid
      */
     public DateTimeFormatterBuilder appendInstant(int fractionalDigits) {
         if (fractionalDigits < -1 || fractionalDigits > 9) {
@@ -909,6 +910,7 @@ public final class DateTimeFormatterBuilder {
      * @param pattern  the pattern to use, not null
      * @param noOffsetText  the text to use when the offset is zero, not null
      * @return this, for chaining, not null
+     * @throws IllegalArgumentException if the pattern is invalid
      */
     public DateTimeFormatterBuilder appendOffset(String pattern, String noOffsetText) {
         appendInternal(new OffsetIdPrinterParser(pattern, noOffsetText));

jdk/src/java.base/share/classes/java/time/package-info.java

@@ -65,7 +65,7 @@
  * The main API for dates, times, instants, and durations.
  * </p>
  * <p>
- * The classes defined here represent the principal date-time concepts,
+ * The classes defined here represent the principle date-time concepts,
  * including instants, durations, dates, times, time-zones and periods.
  * They are based on the ISO calendar system, which is the <i>de facto</i> world
  * calendar following the proleptic Gregorian rules.
@@ -247,8 +247,8 @@
  * </ul>
  * <p>
  * Multiple calendar systems is an awkward addition to the design challenges.
- * The first principal is that most users want the standard ISO calendar system.
- * As such, the main classes are ISO-only. The second principal is that most of those that want a
+ * The first principle is that most users want the standard ISO calendar system.
+ * As such, the main classes are ISO-only. The second principle is that most of those that want a
  * non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
  * As such, date and time objects should be held as ISO objects in the data model and persistent
  * storage, only being converted to and from a local calendar for display.