From 5148a38143d912d4e74a118f0b7131c178962bf3 Mon Sep 17 00:00:00 2001
From: Markus Scherer <markus.icu@gmail.com>
Date: Fri, 21 Sep 2018 16:53:20 -0700
Subject: [PATCH] ICU-20125 numeric values of level constants will not change;
 fix/update some docs (#159)

---
 icu4c/source/common/unicode/ubidi.h           | 10 +++++--
 .../core/src/com/ibm/icu/text/Bidi.java       | 29 ++++++++++++-------
 .../src/com/ibm/icu/text/BidiClassifier.java  |  3 +-
 3 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/icu4c/source/common/unicode/ubidi.h b/icu4c/source/common/unicode/ubidi.h
index 254a5bf9ef..f4875c8801 100644
--- a/icu4c/source/common/unicode/ubidi.h
+++ b/icu4c/source/common/unicode/ubidi.h
@@ -323,6 +323,10 @@
  * these special values are designed that way. Also, the implementation
  * assumes that UBIDI_MAX_EXPLICIT_LEVEL is odd.
  *
+ * Note: The numeric values of the related constants will not change:
+ * They are tied to the use of 7-bit byte values (plus the override bit)
+ * and of the UBiDiLevel=uint8_t data type in this API.
+ *
  * @see UBIDI_DEFAULT_LTR
  * @see UBIDI_DEFAULT_RTL
  * @see UBIDI_LEVEL_OVERRIDE
@@ -386,6 +390,8 @@ typedef uint8_t UBiDiLevel;
 
 /**
  * Maximum explicit embedding level.
+ * Same as the max_depth value in the
+ * <a href="http://www.unicode.org/reports/tr9/#BD2">Unicode Bidirectional Algorithm</a>.
  * (The maximum resolved level can be up to <code>UBIDI_MAX_EXPLICIT_LEVEL+1</code>).
  * @stable ICU 2.0
  */
@@ -1996,7 +2002,7 @@ U_CDECL_BEGIN
  *
  * @return The directional property / Bidi class for the given code point
  *         <code>c</code> if the default class has been overridden, or
- *         <code>#U_BIDI_CLASS_DEFAULT=u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>
+ *         <code>u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>
  *         if the standard Bidi class value for <code>c</code> is to be used.
  * @see ubidi_setClassCallback
  * @see ubidi_getClassCallback
@@ -2010,7 +2016,7 @@ U_CDECL_END
 /**
  * Retrieve the Bidi class for a given code point.
  * <p>If a <code>#UBiDiClassCallback</code> callback is defined and returns a
- * value other than <code>#U_BIDI_CLASS_DEFAULT=u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>,
+ * value other than <code>u_getIntPropertyMaxValue(UCHAR_BIDI_CLASS)+1</code>,
  * that value is used; otherwise the default class determination mechanism is invoked.</p>
  *
  * @param pBiDi is the paragraph <code>UBiDi</code> object.
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/Bidi.java b/icu4j/main/classes/core/src/com/ibm/icu/text/Bidi.java
index 2fb22188a9..6da0d64de9 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/Bidi.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/Bidi.java
@@ -114,7 +114,11 @@ import com.ibm.icu.lang.UProperty;
  * these special values are designed that way. Also, the implementation
  * assumes that MAX_EXPLICIT_LEVEL is odd.
  *
- * <b>See Also:</b>
+ * <p>Note: The numeric values of the related constants will not change:
+ * They are tied to the use of 7-bit byte values (plus the override bit)
+ * and of the byte data type in this API.
+ *
+ * <p><b>See Also:</b>
  * <ul>
  * <li>{@link #LEVEL_DEFAULT_LTR}
  * <li>{@link #LEVEL_DEFAULT_RTL}
@@ -612,6 +616,8 @@ public class Bidi {
 
     /**
      * Maximum explicit embedding level.
+     * Same as the max_depth value in the
+     * <a href="http://www.unicode.org/reports/tr9/#BD2">Unicode Bidirectional Algorithm</a>.
      * (The maximum resolved level can be up to <code>MAX_EXPLICIT_LEVEL+1</code>).
      * @stable ICU 3.8
      */
@@ -4274,9 +4280,10 @@ public class Bidi {
      * in the paragraph.<p>
      *
      * The BIDI_EMBEDDING attribute in the text, if present, represents
-     * embedding level information. Negative values from -1 to -62 indicate
-     * overrides at the absolute value of the level. Positive values from 1 to
-     * 62 indicate embeddings. Where values are zero or not defined, the base
+     * embedding level information.
+     * Negative values indicate overrides at the absolute value of the level.
+     * Positive values indicate embeddings. (See {@link #MAX_EXPLICIT_LEVEL}.)
+     * Where values are zero or not defined, the base
      * embedding level as determined by the base direction is assumed.<p>
      *
      * The NUMERIC_SHAPING attribute in the text, if present, converts European
@@ -4702,7 +4709,7 @@ public class Bidi {
     /**
      * Retrieves the Bidi class for a given code point.
      * <p>If a <code>BidiClassifier</code> is defined and returns a value
-     * other than <code>CLASS_DEFAULT=UCharacter.getIntPropertyMaxValue(UProperty.BIDI_CLASS)+1</code>,
+     * other than <code>UCharacter.getIntPropertyMaxValue(UProperty.BIDI_CLASS)+1</code>,
      * that value is used; otherwise the default class determination mechanism is invoked.
      *
      * @param c The code point to get a Bidi class for.
@@ -5293,9 +5300,10 @@ public class Bidi {
      * in the paragraph.<p>
      *
      * The BIDI_EMBEDDING attribute in the text, if present, represents
-     * embedding level information. Negative values from -1 to -62 indicate
-     * overrides at the absolute value of the level. Positive values from 1 to
-     * 62 indicate embeddings. Where values are zero or not defined, the base
+     * embedding level information.
+     * Negative values indicate overrides at the absolute value of the level.
+     * Positive values indicate embeddings. (See {@link #MAX_EXPLICIT_LEVEL}.)
+     * Where values are zero or not defined, the base
      * embedding level as determined by the base direction is assumed.<p>
      *
      * The NUMERIC_SHAPING attribute in the text, if present, converts European
@@ -5319,9 +5327,8 @@ public class Bidi {
      *
      * <p>The embeddings array may be null. If present, the values represent
      * embedding level information.
-     * Negative values from -1 to -{@link #MAX_EXPLICIT_LEVEL}
-     * indicate overrides at the absolute value of the level.
-     * Positive values from 1 to {@link #MAX_EXPLICIT_LEVEL} indicate embeddings.
+     * Negative values indicate overrides at the absolute value of the level.
+     * Positive values indicate embeddings. (See {@link #MAX_EXPLICIT_LEVEL}.)
      * Where values are zero, the base embedding level
      * as determined by the base direction is assumed,
      * except for paragraph separators which remain at 0 to prevent reordering of paragraphs.</p>
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/BidiClassifier.java b/icu4j/main/classes/core/src/com/ibm/icu/text/BidiClassifier.java
index 71cd645545..9b15750b04 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/BidiClassifier.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/BidiClassifier.java
@@ -86,10 +86,9 @@ public /*abstract*/ class BidiClassifier {
      *
      * @param c Code point to be classified.
      * @return An integer representing directional property / Bidi class for the
-     *         given code point <code>c</code>, or Bidi.CLASS_DEFAULT=UCharacter.getIntPropertyMaxValue(UProperty.BIDI_CLASS)+1
+     *         given code point <code>c</code>, or UCharacter.getIntPropertyMaxValue(UProperty.BIDI_CLASS)+1
      *         to signify that there is no need to override the standard Bidi class for
      *         the given code point.
-     * @see Bidi#CLASS_DEFAULT
      * @stable ICU 3.8
      */
     public int classify(int c) {