1 files changed, 20 insertions, 15 deletions

diff --git a/source/blender/blenkernel/BKE_editmesh.h b/source/blender/blenkernel/BKE_editmesh.h
index 9112877b5a3..ce7df62389f 100644
--- a/source/blender/blenkernel/BKE_editmesh.h
+++ b/source/blender/blenkernel/BKE_editmesh.h
@@ -24,7 +24,7 @@
  * only concerned with low level operations on the #BMEditMesh structure.
  */
 
-#include "BKE_customdata.h"
+#include "DNA_customdata_types.h"
 #include "bmesh.h"
 
 #ifdef __cplusplus
@@ -44,34 +44,39 @@ struct Scene;
 /**
  * This structure is used for mesh edit-mode.
  *
- * through this, you get access to both the edit #BMesh,
- * its tessellation, and various stuff that doesn't belong in the BMesh
- * struct itself.
+ * Through this, you get access to both the edit #BMesh, its tessellation,
+ * and various data that doesn't belong in the #BMesh struct itself
+ * (mostly related to mesh evaluation).
  *
- * the entire derivedmesh and modifier system works with this structure,
- * and not BMesh.  Mesh->edit_bmesh stores a pointer to this structure. */
+ * The entire modifier system works with this structure, and not #BMesh.
+ * #Mesh.edit_bmesh stores a pointer to this structure. */
 typedef struct BMEditMesh {
   struct BMesh *bm;
 
-  /* we store tessellations as triplets of three loops,
-   * which each define a triangle. */
+  /**
+   * Face triangulation (tessellation) is stored as triplets of three loops,
+   * which each define a triangle.
+   *
+   * \see #MLoopTri as the documentation gives useful hints that apply to this data too.
+   */
   struct BMLoop *(*looptris)[3];
   int tottri;
 
   struct Mesh *mesh_eval_final, *mesh_eval_cage;
 
-  /** Cached cage bounding box for selection. */
+  /** Cached cage bounding box of `mesh_eval_cage` for selection. */
   struct BoundBox *bb_cage;
 
   /** Evaluated mesh data-mask. */
   CustomData_MeshMasks lastDataMask;
 
-  /* Selection mode. */
+  /** Selection mode (#SCE_SELECT_VERTEX, #SCE_SELECT_EDGE & #SCE_SELECT_FACE). */
   short selectmode;
+  /** The active material (assigned to newly created faces). */
   short mat_nr;
 
-  /* Temp variables for x-mirror editing. */
-  int mirror_cdlayer; /* -1 is invalid */
+  /** Temp variables for x-mirror editing (-1 when the layer does not exist). */
+  int mirror_cdlayer;
 
   /**
    * ID data is older than edit-mode data.
@@ -94,11 +99,11 @@ void BKE_editmesh_looptri_and_normals_calc_with_partial(BMEditMesh *em,
 
 void BKE_editmesh_looptri_and_normals_calc(BMEditMesh *em);
 
-BMEditMesh *BKE_editmesh_create(BMesh *bm, const bool do_tessellate);
+BMEditMesh *BKE_editmesh_create(BMesh *bm);
 BMEditMesh *BKE_editmesh_copy(BMEditMesh *em);
 BMEditMesh *BKE_editmesh_from_object(struct Object *ob);
-void BKE_editmesh_free_derivedmesh(BMEditMesh *em);
-void BKE_editmesh_free(BMEditMesh *em);
+void BKE_editmesh_free_derived_caches(BMEditMesh *em);
+void BKE_editmesh_free_data(BMEditMesh *em);
 
 float (*BKE_editmesh_vert_coords_alloc(struct Depsgraph *depsgraph,
                                        struct BMEditMesh *em,