From d2c392dec66bb4e66f2ff9e87374e8ede7f26618 Mon Sep 17 00:00:00 2001
From: Campbell Barton <campbell@blender.org>
Date: Thu, 11 Jan 2024 13:56:38 +1100
Subject: [PATCH] Docs: add doc-strings for modifier mapping flags & edit-mesh
 cage

---
 source/blender/blenkernel/BKE_modifier.hh     | 16 ++++++++++++++++
 source/blender/blenkernel/BKE_object_types.hh |  9 ++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/source/blender/blenkernel/BKE_modifier.hh b/source/blender/blenkernel/BKE_modifier.hh
index 87d4f09843c..65e7a55c5e4 100644
--- a/source/blender/blenkernel/BKE_modifier.hh
+++ b/source/blender/blenkernel/BKE_modifier.hh
@@ -68,6 +68,22 @@ enum class ModifierTypeType {
 enum ModifierTypeFlag {
   eModifierTypeFlag_AcceptsMesh = (1 << 0),
   eModifierTypeFlag_AcceptsCVs = (1 << 1),
+  /**
+   * Modifiers that enable this flag can have the modifiers "On Cage" option toggled,
+   * see: #eModifierMode_OnCage, where the output of the modifier can be selected directly.
+   * In some cases the cage geometry use read to tool code as well (loop-cut & knife are examples).
+   *
+   * When set, geometry from the resulting mesh can be mapped back to the original indices
+   * via #CD_ORIGINDEX.
+   *
+   * While many modifiers using this flag preserve the order of geometry arrays,
+   * this isn't always the case, this flag doesn't imply #ModifierTypeType::OnlyDeform.
+   * Geometry from the original mesh may be removed from the resulting mesh or new geometry
+   * may be added (where the #CD_ORIGINDEX value will be #ORIGINDEX_NONE).
+   *
+   * Modifiers that create entirely new geometry from the input should not enable this flag
+   * because none of the geometry will be selectable when "On Cage" is enabled.
+   */
   eModifierTypeFlag_SupportsMapping = (1 << 2),
   eModifierTypeFlag_SupportsEditmode = (1 << 3),
 
diff --git a/source/blender/blenkernel/BKE_object_types.hh b/source/blender/blenkernel/BKE_object_types.hh
index f7629bc1f36..c0c3f072ab8 100644
--- a/source/blender/blenkernel/BKE_object_types.hh
+++ b/source/blender/blenkernel/BKE_object_types.hh
@@ -87,7 +87,14 @@ struct ObjectRuntime {
    */
   Mesh *mesh_deform_eval = nullptr;
 
-  /* Evaluated mesh cage in edit mode. */
+  /**
+   * Evaluated mesh cage in edit mode.
+   *
+   * \note When it's `runtime->deformed_only` is true, the meshes vertex positions
+   * and other geometry arrays will be aligned the edit-mesh.
+   * Otherwise the #CD_ORIGINDEX custom-data should be used to map the cage geometry
+   * back to the original indices, see #eModifierTypeFlag_SupportsMapping.
+   */
   Mesh *editmesh_eval_cage = nullptr;
 
   /**