Clarify some documentation around runes, aka code points

sdk/lib/core/string.dart

Index: sdk/lib/core/string.dart
diff --git a/sdk/lib/core/string.dart b/sdk/lib/core/string.dart
index d780314f2e0a9c59b775303bd0103293a7eca493..6a50b922bb09b2916e369571a6c52e216c462cd3 100644
--- a/sdk/lib/core/string.dart
+++ b/sdk/lib/core/string.dart
@@ -43,7 +43,7 @@ abstract class String implements Comparable<String>, Pattern {
   }
 
   /**
-   * Gets the character (as [String]) at the given [index].
+   * Gets the character (as a single-code-unit [String]) at the given [index].
    *
    * The returned string represents exactly one UTF-16 code unit which may be
    * half of a surrogate pair. For example the Unicode character for a
@@ -84,17 +84,18 @@ abstract class String implements Comparable<String>, Pattern {
   /**
    * Returns whether the two strings are equal.
    *
-   * This method compares each individual code unit of the strings. It does not
-   * check for Unicode equivalence. For example the two following strings both
-   * represent the string "Amélie" but, due to their different encoding will
-   * not return equal.
+   * This method compares each individual code unit of the strings.
+   * Equivalently (for strings that are well-formed UTF-16) it compares each
+   * individual rune (code point).  It does not check for Unicode equivalence.
+   * For example the two following strings both represent the string "Amélie"
+   * but, due to their different encoding will not return equal.
    *
    *     "Am\xe9lie"
    *     "Ame\u{301}lie"
    *
-   * In the first string the "é" is encoded as a single unicode code unit,
-   * whereas the second string encodes it as "e" with the combining
-   * accent character "◌́".
+   * In the first string the "é" is encoded as a single unicode code unit (also
+   * a single rune), whereas the second string encodes it as "e" with the
+   * combining accent character "◌́".
    */
   bool operator ==(var other);
 
@@ -264,7 +265,7 @@ abstract class String implements Comparable<String>, Pattern {
 }
 
 /**
- * The runes of a [String].
+ * The runes (21 bit integer Unicode code points) of a [String].
  */
 class Runes extends Iterable<int> {
   final String string;
@@ -300,7 +301,9 @@ int _combineSurrogatePair(int start, int end) {
   return 0x10000 + ((start & 0x3FF) << 10) + (end & 0x3FF);
 }
 
-/** [Iterator] for reading Unicode code points out of a Dart string. */
+/** [Iterator] for reading runes (21 bit integer Unicode code points) out of a

[Lasse Reichstein Nielsen, 2013/02/28 12:31:21]

You can drop "21 bit integer" if you want, that's redundant when saying "code
points".

+ *  Dart string.
+ */
 class RuneIterator implements BidirectionalIterator<int> {
   /** String being iterated. */
   final String string;
@@ -391,7 +394,8 @@ class RuneIterator implements BidirectionalIterator<int> {
     _currentCodePoint = null;
   }
 
-  /** The rune starting at the current position in the string. */
+  /** The rune (21 bit integer Unicode code point) starting at the current

[Lasse Reichstein Nielsen, 2013/02/28 12:31:21]

Again.

+   *  position in the string. */
   int get current => _currentCodePoint;
 
   /**
@@ -405,7 +409,7 @@ class RuneIterator implements BidirectionalIterator<int> {
    * A string containing the current rune.
    *
    * For runes outside the basic multilingual plane, this will be
-   * a two-character String.
+   * a String of length 2, containing two code units.
    *
    * Returns null if [current] is null.
    */