diff --git a/src/hb-ot-layout-gpos-table.hh b/src/hb-ot-layout-gpos-table.hh
index e95aa3ebb..5b714070f 100644
--- a/src/hb-ot-layout-gpos-table.hh
+++ b/src/hb-ot-layout-gpos-table.hh
@@ -1169,11 +1169,11 @@ struct MarkMarkPosFormat1
     unsigned int j = skippy_iter.idx;
 
     /* Two marks match only if they belong to the same base, or same component
-     * of the same ligature.  That is, the component numbers must match, and
-     * if those are non-zero, the ligid number should also match. */
-    if ((get_lig_comp (c->buffer->info[j]) != get_lig_comp (c->buffer->cur())) ||
-	(get_lig_comp (c->buffer->info[j]) > 0 &&
-	 get_lig_id (c->buffer->info[j]) != get_lig_id (c->buffer->cur())))
+     * of the same ligature.  That is, the lig_id numbers must match, and
+     * if those are non-zero, the lig_comp number should also match. */
+    if ((get_lig_id (c->buffer->info[j]) != get_lig_id (c->buffer->cur())) ||
+	(get_lig_id (c->buffer->info[j]) > 0 &&
+	 get_lig_comp (c->buffer->info[j]) != get_lig_comp (c->buffer->cur())))
       return TRACE_RETURN (false);
 
     unsigned int mark2_index = (this+mark2Coverage) (c->buffer->info[j].codepoint);
diff --git a/src/hb-ot-layout-private.hh b/src/hb-ot-layout-private.hh
index 7a1c7e3f1..ba375aaa7 100644
--- a/src/hb-ot-layout-private.hh
+++ b/src/hb-ot-layout-private.hh
@@ -68,8 +68,27 @@ _hb_ot_layout_skip_mark (hb_face_t    *face,
  * GSUB/GPOS
  */
 
-/* unique ligature id */
-/* component number in the ligature (0 = base) */
+/* lig_id / lig_comp
+ *
+ * When a ligature is formed:
+ *
+ *   - The ligature glyph and any marks in between all get a unique lig_id,
+ *   - The ligature glyph will get lig_comp = 0
+ *   - The marks get lig_comp > 0, reflecting which component of the ligature
+ *     they were applied to.
+ *   - This is used in GPOS to attach marks to the right component of a ligature
+ *     in MarkLigPos.
+ *
+ * When a multiple-substitution is done:
+ *
+ *   - All resulting glyphs will have lig_id = 0,
+ *   - The resulting glyphs will have lig_comp = 0, 1, 2, ... respectively.
+ *   - This is used in GPOS to attack marks to the first component of a
+ *     multiple substitution in MarkBasePos.
+ *
+ * The numbers are also used in GPOS to do mark-to-mark positioning only
+ * to marks that belong to the same component of a ligature in MarkMarPos.
+ */
 static inline void
 set_lig_props (hb_glyph_info_t &info, unsigned int lig_id, unsigned int lig_comp)
 {