@jahia/javascript-modules-library 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahia/javascript-modules-library",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "index.js",
   "types": "types/index.d.ts",
   "repository": "git@github.com:Jahia/javascript-modules.git",
@@ -23,10 +23,31 @@
   "dependencies": {
     "graphql": "^16.0.1",
     "graphql-tag": "^2.12.6",
-    "i18next": "^23.10.1",
-    "prop-types": "^15.8.1",
-    "react": "^18.2.0",
-    "react-i18next": "^14.1.0"
+    "prop-types": "^15.8.1"
+  },
+  "peerDependencies": {
+    "i18next": ">=23.0.0 <23.11.0",
+    "react": ">=18.0.0 <18.3.0",
+    "react-dom": ">=18.0.0 <18.3.0",
+    "react-i18next": ">=14.0.0 <14.2.0",
+    "styled-jsx": ">=5.0.0 <5.2.0"
+  },
+  "peerDependenciesMeta": {
+    "i18next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "react-i18next": {
+      "optional": true
+    },
+    "styled-jsx": {
+      "optional": true
+    }
   },
   "resolutions": {
     "minimist": "^1.2.6",
@@ -51,7 +72,10 @@
     "eslint-plugin-prettier": "^4.0.0",
     "eslint-plugin-react": "^7.32.2",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "i18next": "^23.10.1",
     "ncp": "^2.0.0",
+    "react": "^18.2.0",
+    "react-i18next": "^14.1.0",
     "terser": "^5.36.0",
     "typedoc": "^0.25.13",
     "typescript": "^4.3.5"

package/types/java.io.d.ts

@@ -7,7 +7,7 @@ export class BufferedReader {
    * @return The character read, as an integer in the range
    *         0 to 65535 (`0x00-0xffff`), or -1 if the
    *         end of the stream has been reached
-   * @exception  IOException  If an I/O error occurs
+   * @throws     IOException  If an I/O error occurs
   */
   read(): number;
   /**
@@ -17,22 +17,24 @@ export class BufferedReader {
    * {@link Reader#read(char[], int, int) read} method of the
    * {@link Reader} class.  As an additional convenience, it
    * attempts to read as many characters as possible by repeatedly invoking
-   * the read method of the underlying stream.  This iterated
-   * read continues until one of the following conditions becomes
-   * true: 
+   * the `read` method of the underlying stream.  This iterated
+   * `read` continues until one of the following conditions becomes
+   * true:
+   * 
    *
    *    The specified number of characters have been read,
    *
-   *    The read method of the underlying stream returns
-   *   -1, indicating end-of-file, or
+   *    The `read` method of the underlying stream returns
+   *   `-1`, indicating end-of-file, or
    *
-   *    The ready method of the underlying stream
-   *   returns false, indicating that further input requests
+   *    The `ready` method of the underlying stream
+   *   returns `false`, indicating that further input requests
    *   would block.
    *
-   *  If the first read on the underlying stream returns
-   * -1 to indicate end-of-file then this method returns
-   * -1.  Otherwise this method returns the number of characters
+   * 
+   * If the first `read` on the underlying stream returns
+   * `-1` to indicate end-of-file then this method returns
+   * `-1`.  Otherwise this method returns the number of characters
    * actually read.
    *
    *  Subclasses of this class are encouraged, but not required, to
@@ -43,18 +45,17 @@ export class BufferedReader {
    * however, the buffer is empty, the mark is not valid, and the requested
    * length is at least as large as the buffer, then this method will read
    * characters directly from the underlying stream into the given array.
-   * Thus redundant BufferedReaders will not copy data
+   * Thus redundant `BufferedReader`s will not copy data
    * unnecessarily.
    *
-   * @param      cbuf  Destination buffer
-   * @param      off   Offset at which to start storing characters
-   * @param      len   Maximum number of characters to read
+   * @param      cbuf  {@inheritDoc}
+   * @param      off   {@inheritDoc}
+   * @param      len   {@inheritDoc}
    *
-   * @return     The number of characters read, or -1 if the end of the
-   *             stream has been reached
+   * @return     {@inheritDoc}
    *
-   * @exception  IOException  If an I/O error occurs
-   * @exception  IndexOutOfBoundsException {@inheritDoc}
+   * @throws     IndexOutOfBoundsException {@inheritDoc}
+   * @throws     IOException  {@inheritDoc}
   */
   read(cbuf: string[], off: number, len: number): number;
   /**
@@ -67,7 +68,7 @@ export class BufferedReader {
    *             any line-termination characters, or null if the end of the
    *             stream has been reached without reading any characters
    *
-   * @exception  IOException  If an I/O error occurs
+   * @throws     IOException  If an I/O error occurs
    *
    * @see java.nio.file.Files#readAllLines
   */
@@ -77,7 +78,7 @@ export class BufferedReader {
    * stream is ready if the buffer is not empty, or if the underlying
    * character stream is ready.
    *
-   * @exception  IOException  If an I/O error occurs
+   * @throws     IOException  If an I/O error occurs
   */
   ready(): boolean;
 }
@@ -95,7 +96,7 @@ export class File {
   getName(): string;
   /**
    * Returns the pathname string of this abstract pathname's parent, or
-   * null if this pathname does not name a parent directory.
+   * `null` if this pathname does not name a parent directory.
    *
    *  The parent of an abstract pathname consists of the
    * pathname's prefix, if any, and each name in the pathname's name
@@ -103,13 +104,13 @@ export class File {
    * the pathname does not name a parent directory.
    *
    * @return  The pathname string of the parent directory named by this
-   *          abstract pathname, or null if this pathname
+   *          abstract pathname, or `null` if this pathname
    *          does not name a parent
   */
   getParent(): string;
   /**
    * Returns the abstract pathname of this abstract pathname's parent,
-   * or null if this pathname does not name a parent
+   * or `null` if this pathname does not name a parent
    * directory.
    *
    *  The parent of an abstract pathname consists of the
@@ -118,7 +119,7 @@ export class File {
    * the pathname does not name a parent directory.
    *
    * @return  The abstract pathname of the parent directory named by this
-   *          abstract pathname, or null if this pathname
+   *          abstract pathname, or `null` if this pathname
    *          does not name a parent
    *
    * @since 1.2
@@ -135,12 +136,12 @@ export class File {
   /**
    * Tests whether this abstract pathname is absolute.  The definition of
    * absolute pathname is system dependent.  On UNIX systems, a pathname is
-   * absolute if its prefix is "/".  On Microsoft Windows systems, a
+   * absolute if its prefix is `"/"`.  On Microsoft Windows systems, a
    * pathname is absolute if its prefix is a drive specifier followed by
-   * "\\", or if its prefix is "\\\\".
+   * `"\\"`, or if its prefix is `"\\\\"`.
    *
-   * @return  true if this abstract pathname is absolute,
-   *          false otherwise
+   * @return  `true` if this abstract pathname is absolute,
+   *          `false` otherwise
   */
   isAbsolute(): boolean;
   /**
@@ -150,7 +151,7 @@ export class File {
    * string is simply returned as if by the {@link #getPath}
    * method.  If this abstract pathname is the empty abstract pathname then
    * the pathname string of the current user directory, which is named by the
-   * system property user.dir, is returned.  Otherwise this
+   * system property `user.dir`, is returned.  Otherwise this
    * pathname is resolved in a system-dependent way.  On UNIX systems, a
    * relative pathname is made absolute by resolving it against the current
    * user directory.  On Microsoft Windows systems, a relative pathname is made absolute
@@ -251,9 +252,9 @@ export class File {
    * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
    * Files.readAttributes} method may be used.
    *
-   * @return true if and only if the file denoted by this
+   * @return `true` if and only if the file denoted by this
    *          abstract pathname exists and is a directory;
-   *          false otherwise
+   *          `false` otherwise
    *
    * @throws  SecurityException
    *          If a security manager exists and its {@link
@@ -273,9 +274,9 @@ export class File {
    * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
    * Files.readAttributes} method may be used.
    *
-   * @return  true if and only if the file denoted by this
+   * @return  `true` if and only if the file denoted by this
    *          abstract pathname exists and is a normal file;
-   *          false otherwise
+   *          `false` otherwise
    *
    * @throws  SecurityException
    *          If a security manager exists and its {@link
@@ -287,10 +288,10 @@ export class File {
    * Tests whether the file named by this abstract pathname is a hidden
    * file.  The exact definition of hidden is system-dependent.  On
    * UNIX systems, a file is considered to be hidden if its name begins with
-   * a period character ('.').  On Microsoft Windows systems, a file is
+   * a period character (`'.'`).  On Microsoft Windows systems, a file is
    * considered to be hidden if it has been marked as such in the filesystem.
    *
-   * @return  true if and only if the file denoted by this
+   * @return  `true` if and only if the file denoted by this
    *          abstract pathname is hidden according to the conventions of the
    *          underlying platform
    *
@@ -304,10 +305,13 @@ export class File {
   isHidden(): boolean;
   /**
    * Returns the size of the partition named by this
-   * abstract pathname.
+   * abstract pathname. If the total number of bytes in the partition is
+   * greater than {@link Long#MAX_VALUE}, then `Long.MAX_VALUE` will be
+   * returned.
    *
    * @return  The size, in bytes, of the partition or `0L` if this
-   *          abstract pathname does not name a partition
+   *          abstract pathname does not name a partition or if the size
+   *          cannot be obtained
    *
    * @throws  SecurityException
    *          If a security manager has been installed and it denies
@@ -316,10 +320,13 @@ export class File {
    *          read access to the file named by this abstract pathname
    *
    * @since  1.6
+   * @see FileStore#getTotalSpace
   */
   getTotalSpace(): number;
   /**
-   * Returns the number of unallocated bytes in the partition named by this abstract path name.
+   * Returns the number of unallocated bytes in the partition named by this abstract path name.  If the
+   * number of unallocated bytes in the partition is greater than
+   * {@link Long#MAX_VALUE}, then `Long.MAX_VALUE` will be returned.
    *
    *  The returned number of unallocated bytes is a hint, but not
    * a guarantee, that it is possible to use most or any of these
@@ -331,9 +338,10 @@ export class File {
    * will succeed.
    *
    * @return  The number of unallocated bytes on the partition or `0L`
-   *          if the abstract pathname does not name a partition.  This
-   *          value will be less than or equal to the total file system size
-   *          returned by {@link #getTotalSpace}.
+   *          if the abstract pathname does not name a partition or if this
+   *          number cannot be obtained.  This value will be less than or
+   *          equal to the total file system size returned by
+   *          {@link #getTotalSpace}.
    *
    * @throws  SecurityException
    *          If a security manager has been installed and it denies
@@ -342,28 +350,32 @@ export class File {
    *          read access to the file named by this abstract pathname
    *
    * @since  1.6
+   * @see FileStore#getUnallocatedSpace
   */
   getFreeSpace(): number;
   /**
    * Returns the number of bytes available to this virtual machine on the
-   * partition named by this abstract pathname.  When
-   * possible, this method checks for write permissions and other operating
-   * system restrictions and will therefore usually provide a more accurate
-   * estimate of how much new data can actually be written than {@link
-   * #getFreeSpace}.
+   * partition named by this abstract pathname.  If
+   * the number of available bytes in the partition is greater than
+   * {@link Long#MAX_VALUE}, then `Long.MAX_VALUE` will be returned.
+   * When possible, this method checks for write permissions and other
+   * operating system restrictions and will therefore usually provide a more
+   * accurate estimate of how much new data can actually be written than
+   * {@link #getFreeSpace}.
    *
    *  The returned number of available bytes is a hint, but not a
    * guarantee, that it is possible to use most or any of these bytes.  The
-   * number of unallocated bytes is most likely to be accurate immediately
+   * number of available bytes is most likely to be accurate immediately
    * after this call.  It is likely to be made inaccurate by any external
    * I/O operations including those made on the system outside of this
    * virtual machine.  This method makes no guarantee that write operations
    * to this file system will succeed.
    *
    * @return  The number of available bytes on the partition or `0L`
-   *          if the abstract pathname does not name a partition.  On
-   *          systems where this information is not available, this method
-   *          will be equivalent to a call to {@link #getFreeSpace}.
+   *          if the abstract pathname does not name a partition or if this
+   *          number cannot be obtained.  On systems where this information
+   *          is not available, this method will be equivalent to a call to
+   *          {@link #getFreeSpace}.
    *
    * @throws  SecurityException
    *          If a security manager has been installed and it denies
@@ -372,6 +384,7 @@ export class File {
    *          read access to the file named by this abstract pathname
    *
    * @since  1.6
+   * @see FileStore#getUsableSpace
   */
   getUsableSpace(): number;
 }
@@ -476,9 +489,8 @@ export class PrintWriter {
   print(obj: any): void;
   /**
    * Terminates the current line by writing the line separator string.  The
-   * line separator string is defined by the system property
-   * `line.separator`, and is not necessarily a single newline
-   * character (`'\n'`).
+   * line separator is {@link System#lineSeparator()} and is not necessarily
+   * a single newline character (`'\n'`).
   */
   println(): void;
   /**
@@ -545,7 +557,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *
@@ -592,7 +604,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *
@@ -630,7 +642,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *
@@ -669,7 +681,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *

package/types/java.net.d.ts

@@ -42,7 +42,7 @@ declare module 'java.net' {
  * A URL may have appended to it a "fragment", also known
  * as a "ref" or a "reference". The fragment is indicated by the sharp
  * sign character "#" followed by more characters. For example,
- *  *     http://java.sun.com/index.html#chapter1
+ *  *     http://www.example.com/index.html#chapter1
  * 
  * 
  * This fragment is not technically part of the URL. Rather, it
@@ -55,13 +55,13 @@ declare module 'java.net' {
  * which contains only enough information to reach the resource
  * relative to another URL. Relative URLs are frequently used within
  * HTML pages. For example, if the contents of the URL:
- *  *     http://java.sun.com/index.html
+ *  *     http://www.example.com/index.html
  * 
  * contained within it the relative URL:
  *  *     FAQ.html
  * 
  * it would be a shorthand for:
- *  *     http://java.sun.com/FAQ.html
+ *  *     http://www.example.com/FAQ.html
  * 
  * 
  * The relative URL need not specify all the components of a URL. If
@@ -89,6 +89,26 @@ declare module 'java.net' {
  * used, but only for HTML form encoding, which is not the same
  * as the encoding scheme defined in RFC2396.
  *
+ * @apiNote
+ *
+ * Applications working with file paths and file URIs should take great
+ * care to use the appropriate methods to convert between the two.
+ * The {@link Path#of(URI)} factory method and the {@link File#File(URI)}
+ * constructor can be used to create {@link Path} or {@link File}
+ * objects from a file URI. {@link Path#toUri()} and {@link File#toURI()}
+ * can be used to create a {@link URI} from a file path, which can be
+ * converted to URL using {@link URI#toURL()}.
+ * Applications should never try to {@linkplain #URL(String, String, String)
+ * construct} or {@linkplain #URL(String) parse} a `URL`
+ * from the direct string representation of a `File` or `Path`
+ * instance.
+ * 
+ * Some components of a URL or URI, such as userinfo, may
+ * be abused to construct misleading URLs or URIs. Applications
+ * that deal with URLs or URIs should take into account
+ * the recommendations advised in RFC3986,
+ * Section 7, Security Considerations.
+ *
  * @author  James Gosling
  * @since 1.0
 */
@@ -181,7 +201,7 @@ export class URL {
    * 
    *
    * @return     the contents of this URL.
-   * @exception  IOException  if an I/O exception occurs.
+   * @throws     IOException  if an I/O exception occurs.
    * @see        java.net.URLConnection#getContent()
   */
   getContent(): any;

package/types/java.util.d.ts

@@ -84,11 +84,11 @@ export class Collection<E> {
  * global positioning system (GPS) is synchronized to UTC but is
  * not adjusted for leap seconds. An interesting source of
  * further information is the United States Naval Observatory (USNO):
- *  *     http://www.usno.navy.mil/USNO
+ *  *     https://www.usno.navy.mil/USNO
  * 
  * 
  * and the material regarding "Systems of Time" at:
- *  *     http://www.usno.navy.mil/USNO/time/master-clock/systems-of-time
+ *  *     https://www.usno.navy.mil/USNO/time/master-clock/systems-of-time
  * 
  * 
  * which has descriptions of various different time systems including
@@ -183,7 +183,6 @@ export class Date {
  * NOTE: This class is obsolete.  New implementations should
  * implement the Map interface, rather than extending this class.
  *
- * @author  unascribed
  * @see     java.util.Map
  * @see     java.lang.Object#equals(java.lang.Object)
  * @see     java.lang.Object#hashCode()
@@ -216,7 +215,7 @@ export class Dictionary<K, V> {
    * @param   key   a key in this dictionary.
    *          `null` if the key is not mapped to any value in
    *          this dictionary.
-   * @exception NullPointerException if the `key` is `null`.
+   * @throws    NullPointerException if the `key` is `null`.
    * @see     java.util.Dictionary#put(java.lang.Object, java.lang.Object)
   */
   get(key: any): V;
@@ -270,7 +269,7 @@ export class Enumeration<E> {
    * object has at least one more element to provide.
    *
    * @return     the next element of this enumeration.
-   * @exception  NoSuchElementException  if no more elements exist.
+   * @throws     NoSuchElementException  if no more elements exist.
   */
   nextElement(): E;
 }
@@ -351,9 +350,9 @@ export class List<E> {
   get(index: number): E;
 }
 /**
- * A Locale object represents a specific geographical, political,
- * or cultural region. An operation that requires a Locale to perform
- * its task is called locale-sensitive and uses the Locale
+ * A `Locale` object represents a specific geographical, political,
+ * or cultural region. An operation that requires a `Locale` to perform
+ * its task is called locale-sensitive and uses the `Locale`
  * to tailor information for the user. For example, displaying a number
  * is a locale-sensitive operation— the number should be formatted
  * according to the customs and conventions of the user's native country,
@@ -366,7 +365,7 @@ export class List<E> {
  * Locale Data Markup Language") BCP 47-compatible extensions for locale data
  * exchange.
  *
- *  A Locale object logically consists of the fields
+ *  A `Locale` object logically consists of the fields
  * described below.
  *
  * 
@@ -378,7 +377,7 @@ export class List<E> {
  *   alpha-2 code must be used.  You can find a full list of valid
  *   language codes in the IANA Language Subtag Registry (search for
  *   "Type: language").  The language field is case insensitive, but
- *   Locale always canonicalizes to lower case.
+ *   `Locale` always canonicalizes to lower case.
  *
  *   Well-formed language values have the form
  *   [a-zA-Z]{2,8}.  Note that this is not the full
@@ -393,7 +392,7 @@ export class List<E> {
  *   ISO 15924 alpha-4 script code.  You can find a full list of
  *   valid script codes in the IANA Language Subtag Registry (search
  *   for "Type: script").  The script field is case insensitive, but
- *   Locale always canonicalizes to title case (the first
+ *   `Locale` always canonicalizes to title case (the first
  *   letter is upper case and the rest of the letters are lower
  *   case).
  *
@@ -408,7 +407,7 @@ export class List<E> {
  *   You can find a full list of valid country and region codes in the
  *   IANA Language Subtag Registry (search for "Type: region").  The
  *   country (region) field is case insensitive, but
- *   Locale always canonicalizes to upper case.
+ *   `Locale` always canonicalizes to upper case.
  *
  *   Well-formed country/region values have
  *   the form [a-zA-Z]{2} | [0-9]{3}
@@ -419,7 +418,7 @@ export class List<E> {
  *   variant
  *
  *   Any arbitrary value used to indicate a variation of a
- *   Locale.  Where there are two or more variant values
+ *   `Locale`.  Where there are two or more variant values
  *   each indicating its own semantics, these values should be ordered
  *   by importance, with most important first, separated by
  *   underscore('_').  The variant field is case sensitive.
@@ -431,7 +430,7 @@ export class List<E> {
  *   region subtags.  You can find a full list of valid variant codes
  *   in the IANA Language Subtag Registry (search for "Type: variant").
  *
- *   However, the variant field in Locale has
+ *   However, the variant field in `Locale` has
  *   historically been used for any kind of variation, not just
  *   language variations.  For example, some supported variants
  *   available in Java SE Runtime Environments indicate alternative
@@ -451,15 +450,15 @@ export class List<E> {
  *
  *   A map from single character keys to string values, indicating
  *   extensions apart from language identification.  The extensions in
- *   Locale implement the semantics and syntax of BCP 47
+ *   `Locale` implement the semantics and syntax of BCP 47
  *   extension subtags and private use subtags. The extensions are
- *   case insensitive, but Locale canonicalizes all
+ *   case insensitive, but `Locale` canonicalizes all
  *   extension keys and values to lower case. Note that extensions
  *   cannot have empty values.
  *
  *   Well-formed keys are single characters from the set
- *   [0-9a-zA-Z].  Well-formed values have the form
- *   SUBTAG ('-' SUBTAG)* where for the key 'x'
+ *   `[0-9a-zA-Z]`.  Well-formed values have the form
+ *   `SUBTAG ('-' SUBTAG)*` where for the key 'x'
  *   SUBTAG = [0-9a-zA-Z]{1,8} and for other keys
  *   SUBTAG = [0-9a-zA-Z]{2,8} (that is, 'x' allows
  *   single-character subtags).
@@ -469,8 +468,8 @@ export class List<E> {
  * 
  *
  * Note: Although BCP 47 requires field values to be registered
- * in the IANA Language Subtag Registry, the Locale class
- * does not provide any validation features.  The Builder
+ * in the IANA Language Subtag Registry, the `Locale` class
+ * does not provide any validation features.  The `Builder`
  * only checks if an individual field satisfies the syntactic
  * requirement (is well-formed), but does not validate the value
  * itself.  See {@link Builder} for details.
@@ -488,11 +487,11 @@ export class List<E> {
  * extension key 'u' ({@link #UNICODE_LOCALE_EXTENSION}).  The above
  * example, "nu-thai", becomes the extension "u-nu-thai".
  *
- * Thus, when a Locale object contains Unicode locale
+ * Thus, when a `Locale` object contains Unicode locale
  * attributes and keywords,
- * getExtension(UNICODE_LOCALE_EXTENSION) will return a
+ * `getExtension(UNICODE_LOCALE_EXTENSION)` will return a
  * String representing this information, for example, "nu-thai".  The
- * Locale class also provides {@link
+ * `Locale` class also provides {@link
  * #getUnicodeLocaleAttributes}, {@link #getUnicodeLocaleKeys}, and
  * {@link #getUnicodeLocaleType} which allow you to access Unicode
  * locale attributes and key/type pairs directly.  When represented as
@@ -517,37 +516,37 @@ export class List<E> {
  *
  * Creating a Locale
  *
- * There are several different ways to create a Locale
+ * There are several different ways to create a `Locale`
  * object.
  *
  * Builder
  *
- * Using {@link Builder} you can construct a Locale object
+ * Using {@link Builder} you can construct a `Locale` object
  * that conforms to BCP 47 syntax.
  *
  * Constructors
  *
- * The Locale class provides three constructors:
+ * The `Locale` class provides three constructors:
  * 
  *  *     {@link #Locale(String language)}
  *     {@link #Locale(String language, String country)}
  *     {@link #Locale(String language, String country, String variant)}
  * 
  * 
- * These constructors allow you to create a Locale object
+ * These constructors allow you to create a `Locale` object
  * with language, country and variant, but you cannot specify
  * script or extensions.
  *
  * Factory Methods
  *
- * The method {@link #forLanguageTag} creates a Locale
+ * The method {@link #forLanguageTag} creates a `Locale`
  * object for a well-formed BCP 47 language tag.
  *
  * Locale Constants
  *
- * The Locale class provides a number of convenient constants
- * that you can use to create Locale objects for commonly used
- * locales. For example, the following creates a Locale object
+ * The `Locale` class provides a number of convenient constants
+ * that you can use to create `Locale` objects for commonly used
+ * locales. For example, the following creates a `Locale` object
  * for the United States:
  * 
  *  *     Locale.US
@@ -626,25 +625,25 @@ export class List<E> {
  *
  * Use of Locale
  *
- * Once you've created a Locale you can query it for information
- * about itself. Use getCountry to get the country (or region)
- * code and getLanguage to get the language code.
- * You can use getDisplayCountry to get the
+ * Once you've created a `Locale` you can query it for information
+ * about itself. Use `getCountry` to get the country (or region)
+ * code and `getLanguage` to get the language code.
+ * You can use `getDisplayCountry` to get the
  * name of the country suitable for displaying to the user. Similarly,
- * you can use getDisplayLanguage to get the name of
+ * you can use `getDisplayLanguage` to get the name of
  * the language suitable for displaying to the user. Interestingly,
- * the getDisplayXXX methods are themselves locale-sensitive
+ * the `getDisplayXXX` methods are themselves locale-sensitive
  * and have two versions: one that uses the default
  * {@link Locale.Category#DISPLAY DISPLAY} locale and one
  * that uses the locale specified as an argument.
  *
  * The Java Platform provides a number of classes that perform locale-sensitive
- * operations. For example, the NumberFormat class formats
+ * operations. For example, the `NumberFormat` class formats
  * numbers, currency, and percentages in a locale-sensitive manner. Classes
- * such as NumberFormat have several convenience methods
+ * such as `NumberFormat` have several convenience methods
  * for creating a default object of that type. For example, the
- * NumberFormat class provides these three convenience methods
- * for creating a default NumberFormat object:
+ * `NumberFormat` class provides these three convenience methods
+ * for creating a default `NumberFormat` object:
  * 
  *  *     NumberFormat.getInstance()
  *     NumberFormat.getCurrencyInstance()
@@ -660,8 +659,8 @@ export class List<E> {
  *     NumberFormat.getPercentInstance(myLocale)
  * 
  * 
- * A Locale is the mechanism for identifying the kind of object
- * (NumberFormat) that you would like to get. The locale is
+ * A `Locale` is the mechanism for identifying the kind of object
+ * (`NumberFormat`) that you would like to get. The locale is
  * just a mechanism for identifying objects,
  * not a container for the objects themselves.
  *
@@ -670,7 +669,7 @@ export class List<E> {
  * In order to maintain compatibility with existing usage, Locale's
  * constructors retain their behavior prior to the Java Runtime
  * Environment version 1.7.  The same is largely true for the
- * toString method. Thus Locale objects can continue to
+ * `toString` method. Thus Locale objects can continue to
  * be used as they were. In particular, clients who parse the output
  * of toString into language, country, and variant fields can continue
  * to do so (although this is strongly discouraged), although the
@@ -680,15 +679,15 @@ export class List<E> {
  * In addition, BCP 47 imposes syntax restrictions that are not
  * imposed by Locale's constructors. This means that conversions
  * between some Locales and BCP 47 language tags cannot be made without
- * losing information. Thus toLanguageTag cannot
+ * losing information. Thus `toLanguageTag` cannot
  * represent the state of locales whose language, country, or variant
  * do not conform to BCP 47.
  *
  * Because of these issues, it is recommended that clients migrate
  * away from constructing non-conforming locales and use the
- * forLanguageTag and Locale.Builder APIs instead.
+ * `forLanguageTag` and `Locale.Builder` APIs instead.
  * Clients desiring a string representation of the complete locale can
- * then always rely on toLanguageTag for this purpose.
+ * then always rely on `toLanguageTag` for this purpose.
  *
  * Special cases
  *
@@ -729,14 +728,24 @@ export class List<E> {
  * Locale's constructor has always converted three language codes to
  * their earlier, obsoleted forms: `he` maps to `iw`,
  * `yi` maps to `ji`, and `id` maps to
- * `in`.  This continues to be the case, in order to not break
- * backwards compatibility.
+ * `in`. Since Java SE 17, this is no longer the case. Each
+ * language maps to its new form; `iw` maps to `he`, `ji`
+ * maps to `yi`, and `in` maps to `id`.
+ *
+ * For the backward compatible behavior, the system property
+ * {@systemProperty java.locale.useOldISOCodes} reverts the behavior
+ * back to that of before Java SE 17. If the system property is set to
+ * `true`, those three current language codes are mapped to their
+ * backward compatible forms. The property is only read at Java runtime
+ * startup and subsequent calls to `System.setProperty()` will
+ * have no effect.
  *
  * The APIs added in 1.7 map between the old and new language codes,
- * maintaining the old codes internal to Locale (so that
- * getLanguage and toString reflect the old
- * code), but using the new codes in the BCP 47 language tag APIs (so
- * that toLanguageTag reflects the new one). This
+ * maintaining the mapped codes internal to Locale (so that
+ * `getLanguage` and `toString` reflect the mapped
+ * code, which depends on the `java.locale.useOldISOCodes` system
+ * property), but using the new codes in the BCP 47 language tag APIs (so
+ * that `toLanguageTag` reflects the new one). This
  * preserves the equivalence between Locales no matter which code or
  * API is used to construct them. Java's default resource bundle
  * lookup mechanism also implements this mapping, so that resources
@@ -781,7 +790,7 @@ export class Locale {
    * The returned array represents the union of locales supported
    * by the Java runtime environment and by installed
    * {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
-   * implementations.  It must contain at least a Locale
+   * implementations.  It must contain at least a `Locale`
    * instance equal to {@link java.util.Locale#US Locale.US}.
    *
    * @return An array of installed locales.
@@ -793,7 +802,7 @@ export class Locale {
    * This method is equivalent to {@link #getISOCountries(Locale.IsoCountryCode type)}
    * with `type`  {@link IsoCountryCode#PART1_ALPHA2}.
    * 
-   * Note: The Locale class also supports other codes for
+   * Note: The `Locale` class also supports other codes for
    * country (region), such as 3-letter numeric UN M.49 area codes.
    * Therefore, the list returned by this method does not contain ALL valid
    * codes that can be used to create Locales.
@@ -814,7 +823,7 @@ export class Locale {
    * ISO 639 is not a stable standard— some languages' codes have changed.
    * The list this function returns includes both the new and the old codes for the
    * languages whose codes have changed.
-   * The Locale class also supports language codes up to
+   * The `Locale` class also supports language codes up to
    * 8 characters in length.  Therefore, the list returned by this method does
    * not contain ALL valid codes that can be used to create Locales.
    * 
@@ -825,17 +834,10 @@ export class Locale {
   /**
    * Returns the language code of this Locale.
    *
-   * Note: ISO 639 is not a stable standard— some languages' codes have changed.
-   * Locale's constructor recognizes both the new and the old codes for the languages
-   * whose codes have changed, but this function always returns the old code.  If you
-   * want to check for a specific language whose code has changed, don't do
-   *      * if (locale.getLanguage().equals("he")) // BAD!
-   *    ...
-   * 
-   * Instead, do
-   *      * if (locale.getLanguage().equals(new Locale("he").getLanguage()))
-   *    ...
-   * 
+   * @implNote This method returns the new forms for the obsolete ISO 639
+   * codes ("iw", "ji", and "in"). See 
+   * Legacy language codes for more information.
+   *
    * @return The language code, or the empty string if none is defined.
    * @see #getDisplayLanguage
   */
@@ -871,7 +873,7 @@ export class Locale {
    * Returns the extension (or private use) value associated with
    * the specified key, or null if there is no extension
    * associated with the key. To be well-formed, the key must be one
-   * of [0-9A-Za-z]. Keys are case-insensitive, so
+   * of `[0-9A-Za-z]`. Keys are case-insensitive, so
    * for example 'z' and 'Z' represent the same extension.
    *
    * @param key the extension key
@@ -913,7 +915,7 @@ export class Locale {
    * @return The Unicode locale type associated with the key, or null if the
    * locale does not define the key.
    * @throws IllegalArgumentException if the key is not well-formed
-   * @throws NullPointerException if key is null
+   * @throws NullPointerException if `key` is null
    * @since 1.7
   */
   getUnicodeLocaleType(key: string): string;
@@ -927,7 +929,7 @@ export class Locale {
   */
   getUnicodeLocaleKeys(): Set<string>;
   /**
-   * Returns a string representation of this Locale
+   * Returns a string representation of this `Locale`
    * object, consisting of language, country, variant, script,
    * and extensions as below:
    * 
@@ -950,7 +952,7 @@ export class Locale {
    * added before the "#".
    *
    * This behavior is designed to support debugging and to be compatible with
-   * previous uses of toString that expected language, country, and variant
+   * previous uses of `toString` that expected language, country, and variant
    * fields only.  To represent a Locale as a String for interchange purposes, use
    * {@link #toLanguageTag}.
    *
@@ -980,7 +982,7 @@ export class Locale {
    * not specify a language the empty string is returned.
    *
    * @return A three-letter abbreviation of this locale's language.
-   * @exception MissingResourceException Throws MissingResourceException if
+   * @throws    MissingResourceException Throws MissingResourceException if
    * three-letter language abbreviation is not available for this locale.
   */
   getISO3Language(): string;
@@ -994,7 +996,7 @@ export class Locale {
    * The ISO 3166-1 codes can be found on-line.
    *
    * @return A three-letter abbreviation of this locale's country.
-   * @exception MissingResourceException Throws MissingResourceException if the
+   * @throws    MissingResourceException Throws MissingResourceException if the
    * three-letter country abbreviation is not available for this locale.
   */
   getISO3Country(): string;
@@ -1032,7 +1034,7 @@ export class Locale {
    *
    * @param inLocale The locale for which to retrieve the display language.
    * @return The name of the display language appropriate to the given locale.
-   * @exception NullPointerException if inLocale is null
+   * @throws    NullPointerException if `inLocale` is `null`
   */
   getDisplayLanguage(inLocale: Locale): string;
   /**
@@ -1055,7 +1057,7 @@ export class Locale {
    * @param inLocale The locale for which to retrieve the display script.
    * @return the display name of the script code for the current default
    * {@link Locale.Category#DISPLAY DISPLAY} locale
-   * @throws NullPointerException if inLocale is null
+   * @throws NullPointerException if `inLocale` is `null`
    * @since 1.7
   */
   getDisplayScript(inLocale: Locale): string;
@@ -1093,7 +1095,7 @@ export class Locale {
    *
    * @param inLocale The locale for which to retrieve the display country.
    * @return The name of the country appropriate to the given locale.
-   * @exception NullPointerException if inLocale is null
+   * @throws    NullPointerException if `inLocale` is `null`
   */
   getDisplayCountry(inLocale: Locale): string;
   /**
@@ -1112,7 +1114,7 @@ export class Locale {
    *
    * @param inLocale The locale for which to retrieve the display variant code.
    * @return The name of the display variant code appropriate to the given locale.
-   * @exception NullPointerException if inLocale is null
+   * @throws    NullPointerException if `inLocale` is `null`
   */
   getDisplayVariant(inLocale: Locale): string;
   /**
@@ -1159,7 +1161,7 @@ export class Locale {
    *
    * @param inLocale The locale for which to retrieve the display name.
    * @return The name of the locale appropriate to display.
-   * @throws NullPointerException if inLocale is null
+   * @throws NullPointerException if `inLocale` is `null`
   */
   getDisplayName(inLocale: Locale): string;
 }
@@ -1264,10 +1266,12 @@ export class Locale {
  * passed to a static factory method result in `IllegalArgumentException`.
  * The iteration order of mappings is unspecified and is subject to change.
  * They are value-based.
- * Callers should make no assumptions about the identity of the returned instances.
- * Factories are free to create new instances or reuse existing ones. Therefore,
- * identity-sensitive operations on these instances (reference equality (`==`),
- * identity hash code, and synchronization) are unreliable and should be avoided.
+ * Programmers should treat instances that are {@linkplain #equals(Object) equal}
+ * as interchangeable and should not use them for synchronization, or
+ * unpredictable behavior may occur. For example, in a future release,
+ * synchronization may fail. Callers should make no assumptions
+ * about the identity of the returned instances. Factories are free to
+ * create new instances or reuse existing ones.
  * They are serialized as specified on the
  * Serialized Form
  * page.
@@ -1423,7 +1427,7 @@ export class Map<K, V> {
    * `null`, else returns the current value.
    *
    * @implSpec
-   * The default implementation is equivalent to, for this `     * map`:
+   * The default implementation is equivalent to, for this `map`:
    *
    *  {@code
    * V v = map.get(key);