Summary

Update the Javadoc of java.time.temporal.WeekFields.of(Locale) to include an example snippet of a custom Locale that is English and has ISO-8601 qualities.

Problem

User(s) wanted a Locale that is both English and follows certain ISO-8601 standards, but there is not enough motivation to create such a Locale constant.

Solution

As an alternative, an example snippet can be included that demonstrates how such a custom Locale could be created and used through existing JDK methods. Creating the locale using the BCP 47 string tag allows user's to bypass certain country related customs as well, with the flexibility of setting Unicode extensions. This allows the user to create an English language locale, with an ISO-8601 conforming first day of the week, and no country related conventions.

Specification

+     * <p>For example, users who are interested in using an English locale,
+     * but want the first day of the week that corresponds with the ISO-8601
+     * standard can call
+     * {@snippet lang=java :
+     * Locale enIsoLoc = Locale.forLanguageTag("en-u-fw-mon");
+     * WeekFields.of(enIsoLoc).getFirstDayOfWeek(); // returns MONDAY
+     * }
+     *
      * @param locale  the locale to use, not null
      * @return the week-definition, not null
      */
      public static WeekFields of(Locale locale) {