[docs] Improve UNSAFE_TO_BREAK docs

1 files changed, 15 insertions, 2 deletions

diff --git a/src/hb-buffer.h b/src/hb-buffer.h
index 9f86b494..cf182db1 100644
--- a/src/hb-buffer.h
+++ b/src/hb-buffer.h
@@ -73,8 +73,21 @@ typedef struct hb_glyph_info_t {
 
 /**
  * hb_glyph_flags_t:
- * @HB_GLYPH_FLAG_UNSAFE_TO_BREAK: If this glyph is split from the previous logical glyph
- *                                 then both sides should be re-shaped.
+ * @HB_GLYPH_FLAG_UNSAFE_TO_BREAK: Indicates that if input text is broken at the
+ * 				   beginning of the cluster this glyph is part of,
+ * 				   then both sides need to be re-shaped, as the
+ * 				   result might be different.  On the flip side,
+ * 				   it means that when this flag is not present,
+ * 				   then it's safe to break the glyph-run at the
+ * 				   beginning of this cluster, and the two sides
+ * 				   represent the exact same result one would get
+ * 				   if breaking input text at the beginning of
+ * 				   this cluster ans shaping the two sides
+ * 				   separately.  This can be used to optimize
+ * 				   paragraph layout, by avoiding re-shaping
+ * 				   of each line after line-breaking, or limiting
+ * 				   the reshaping to a small piece around the
+ * 				   breaking point only.
  */
 typedef enum { /*< flags >*/
   HB_GLYPH_FLAG_UNSAFE_TO_BREAK		= 0x00000001,