[docs] Improve UNSAFE_TO_BREAK docs
diff --git a/src/hb-buffer.h b/src/hb-buffer.h
index 9f86b49..cf182db 100644
--- a/src/hb-buffer.h
+++ b/src/hb-buffer.h
@@ -73,8 +73,21 @@
/**
* 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,
