7000507: javadoc warnings in java.util.Locale

7004335: Javadoc for Locale.toLangaugeTag() is unclear
7005320: (lc) doc: missing " in Locale.forLanguageTag code samples
Reviewed-by: okutsu

src/share/classes/java/util/Locale.java

@@ -870,7 +870,7 @@ public final class Locale implements Cloneable, Serializable {
      * @throws SecurityException - if a security manager exists and its
      *     checkPermission method doesn't allow the operation.
      * @throws NullPointerException - if category and/or newLocale is null
-     * @see SecurityManager.checkPermission(java.security.Permission)
+     * @see SecurityManager#checkPermission(java.security.Permission)
      * @see PropertyPermission
      * @see #getDefault(Locale.Category)
      * @since 1.7
@@ -1232,20 +1232,18 @@ public final class Locale implements Cloneable, Serializable {
      * "Solaris_isjustthecoolestthing" is emitted as
      * "x-lvariant-Solaris", not as "solaris".</li></ul>
      *
-     * <p><b>Compatibility special cases:</b><ul>
+     * <p><b>Special Conversions:</b> Java supports some old locale
+     * representations, including deprecated ISO language codes,
+     * for compatibility. This method performs the following
+     * conversions:
+     * <ul>
      *
-     * <li>The language codes "iw", "ji", and "in" are handled
-     * specially. Java uses these deprecated codes for compatibility
-     * reasons. The <code>toLanguageTag</code> method converts these
-     * three codes (and only these three) to "he", "yi", and "id"
-     * respectively.
+     * <li>Deprecated ISO language codes "iw", "ji", and "in" are
+     * converted to "he", "yi", and "id", respectively.
      *
      * <li>A locale with language "no", country "NO", and variant
-     * "NY", representing Norwegian Nynorsk, will be represented as
-     * having language "nn", country "NO", and empty variant. This is
-     * because some JVMs used the deprecated form to represent the
-     * user's default locale, and for compatibility reasons that Take a has
-     * not been changed.</ul>
+     * "NY", representing Norwegian Nynorsk (Norway), is converted
+     * to a language tag "nn-NO".</li></ul>
      *
      * <p><b>Note:</b> Although the language tag created by this
      * method is well-formed (satisfies the syntax requirements
@@ -1327,7 +1325,7 @@ public final class Locale implements Cloneable, Serializable {
      *
      * <pre>
      *     Locale loc;
-     *     loc = Locale.forLanguageTag("en-US-x-lvariant-POSIX);
+     *     loc = Locale.forLanguageTag("en-US-x-lvariant-POSIX");
      *     loc.getVariant(); // returns "POSIX"
      *     loc.getExtension('x'); // returns null
      *
@@ -1355,10 +1353,10 @@ public final class Locale implements Cloneable, Serializable {
      * extensions are added as though the constructor had been called:
      *
      * <pre>
-     *    Locale.forLanguageTag("ja-JP-x-lvariant-JP).toLanguageTag();
-     *    // returns ja-JP-u-ca-japanese-x-lvariant-JP
-     *    Locale.forLanguageTag("th-TH-x-lvariant-TH).toLanguageTag();
-     *    // returns th-TH-u-nu-thai-x-lvariant-TH
+     *    Locale.forLanguageTag("ja-JP-x-lvariant-JP").toLanguageTag();
+     *    // returns "ja-JP-u-ca-japanese-x-lvariant-JP"
+     *    Locale.forLanguageTag("th-TH-x-lvariant-TH").toLanguageTag();
+     *    // returns "th-TH-u-nu-thai-x-lvariant-TH"
      * <pre></ul>
      *
      * <p>This implements the 'Language-Tag' production of BCP47, and