- * When the cursor position is i, is the cursor after the i-th char
- * or before the i+1-th char ? Normally, these two interpretations are
- * equivalent, except when the fonts of the i-th and i+1-th char
- * differ.
- * We use boundary_ to distinguish between the two options:
- * If boundary_=true, then the cursor is after the i-th char
- * and if boundary_=false, then the cursor is before the i+1-th char.
+ * Normally, when the cursor is at position i, it is painted *before*
+ * the character at position i. However, what if we want the cursor
+ * painted *after* position i? That's what boundary_ is for: if
+ * boundary_==true, the cursor is painted *after* position i-1, instead
+ * of before position i.
+ *
+ * Note 1: Usually, after i-1 or before i are actually the same place!
+ * However, this is not the case when i-1 and i are not painted
+ * contiguously, and in these cases we sometimes do want to have control
+ * over whether to paint before i or after i-1.
+ * Some concrete examples of where this happens:
+ * a. i-1 at the end of one row, i at the beginning of next row
+ * b. in bidi text, at transitions between RTL and LTR or vice versa