Docs: add doc-strings for modifier mapping flags & edit-mesh cage

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),
 

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;
 
   /**