Cleanup: doxy sections for editmesh files.

4 files changed, 347 insertions, 185 deletions

diff --git a/source/blender/editors/mesh/editmesh_add.c b/source/blender/editors/mesh/editmesh_add.c
index 77772cfc8cc..22cb28f0b1b 100644
--- a/source/blender/editors/mesh/editmesh_add.c
+++ b/source/blender/editors/mesh/editmesh_add.c
@@ -60,9 +60,10 @@
 
 /* ********* add primitive operators ************* */
 
-static Object *make_prim_init(bContext *C, const char *idname,
-                              float *dia, float mat[4][4],
-                              bool *was_editmode, const float loc[3], const float rot[3], const unsigned int layer)
+static Object *make_prim_init(
+        bContext *C, const char *idname,
+        float *dia, float mat[4][4],
+        bool *was_editmode, const float loc[3], const float rot[3], const unsigned int layer)
 {
 	Object *obedit = CTX_data_edit_object(C);
 
diff --git a/source/blender/editors/mesh/editmesh_extrude.c b/source/blender/editors/mesh/editmesh_extrude.c
index 5ac90ec29e6..2c98f05bd27 100644
--- a/source/blender/editors/mesh/editmesh_extrude.c
+++ b/source/blender/editors/mesh/editmesh_extrude.c
@@ -54,6 +54,10 @@
 
 #include "mesh_intern.h"  /* own include */
 
+/* -------------------------------------------------------------------- */
+/** \name Extrude Internal Utilities
+ * \{ */
+
 static void edbm_extrude_edge_exclude_mirror(
         Object *obedit, BMEditMesh *em,
         const char hflag,
@@ -142,7 +146,7 @@ static bool edbm_extrude_discrete_faces(BMEditMesh *em, wmOperator *op, const ch
 	EDBM_flag_disable_all(em, BM_ELEM_SELECT);
 
 	BMO_op_exec(em->bm, &bmop);
-	
+
 	BMO_ITER (f, &siter, bmop.slots_out, "faces.out", BM_FACE) {
 		BM_face_select_set(em->bm, f, true);
 
@@ -242,7 +246,7 @@ static bool edbm_extrude_ex(
 	BMOIter siter;
 	BMOperator extop;
 	BMElem *ele;
-	
+
 	/* needed to remove the faces left behind */
 	if (htype & BM_FACE) {
 		htype |= BM_EDGE;
@@ -264,7 +268,7 @@ static bool edbm_extrude_ex(
 	BM_SELECT_HISTORY_RESTORE(bm);
 
 	BMO_op_exec(bm, &extop);
-	
+
 	BMO_ITER (ele, &siter, extop.slots_out, "geom.out", BM_ALL_NOLOOP) {
 		BM_elem_select_set(bm, ele, true);
 	}
@@ -274,14 +278,20 @@ static bool edbm_extrude_ex(
 	return true;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Extrude Repeat Operator
+ * \{ */
+
 static int edbm_extrude_repeat_exec(bContext *C, wmOperator *op)
 {
 	Object *obedit = CTX_data_edit_object(C);
 	BMEditMesh *em = BKE_editmesh_from_object(obedit);
 	RegionView3D *rv3d = CTX_wm_region_view3d(C);
-		
+
 	const int steps = RNA_int_get(op->ptr, "steps");
-	
+
 	const float offs = RNA_float_get(op->ptr, "offset");
 	float dvec[3], tmat[3][3], bmat[3][3];
 	short a;
@@ -302,7 +312,7 @@ static int edbm_extrude_repeat_exec(bContext *C, wmOperator *op)
 		        "translate vec=%v verts=%hv",
 		        dvec, BM_ELEM_SELECT);
 	}
-	
+
 	EDBM_mesh_normals_update(em);
 
 	EDBM_update_generic(em, true, true);
@@ -316,19 +326,25 @@ void MESH_OT_extrude_repeat(wmOperatorType *ot)
 	ot->name = "Extrude Repeat Mesh";
 	ot->description = "Extrude selected vertices, edges or faces repeatedly";
 	ot->idname = "MESH_OT_extrude_repeat";
-	
+
 	/* api callbacks */
 	ot->exec = edbm_extrude_repeat_exec;
 	ot->poll = ED_operator_editmesh_view3d;
-	
+
 	/* flags */
 	ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
-	
+
 	/* props */
 	RNA_def_float_distance(ot->srna, "offset", 2.0f, 0.0f, 1e12f, "Offset", "", 0.0f, 100.0f);
 	RNA_def_int(ot->srna, "steps", 10, 0, 1000000, "Steps", "", 0, 180);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Extrude Operator
+ * \{ */
+
 /* generic extern called extruder */
 static bool edbm_extrude_mesh(Object *obedit, BMEditMesh *em, wmOperator *op)
 {
@@ -365,7 +381,7 @@ static bool edbm_extrude_mesh(Object *obedit, BMEditMesh *em, wmOperator *op)
 			changed = edbm_extrude_edges_indiv(em, op, BM_ELEM_SELECT);
 			break;
 	}
-	
+
 	if (changed) {
 		return true;
 	}
@@ -380,7 +396,7 @@ static int edbm_extrude_region_exec(bContext *C, wmOperator *op)
 {
 	Object *obedit = CTX_data_edit_object(C);
 	BMEditMesh *em = BKE_editmesh_from_object(obedit);
-	
+
 	edbm_extrude_mesh(obedit, em, op);
 
 	/* This normally happens when pushing undo but modal operators
@@ -389,7 +405,7 @@ static int edbm_extrude_region_exec(bContext *C, wmOperator *op)
 	EDBM_mesh_normals_update(em);
 
 	EDBM_update_generic(em, true, true);
-	
+
 	return OPERATOR_FINISHED;
 }
 
@@ -399,27 +415,33 @@ void MESH_OT_extrude_region(wmOperatorType *ot)
 	ot->name = "Extrude Region";
 	ot->idname = "MESH_OT_extrude_region";
 	ot->description = "Extrude region of faces";
-	
+
 	/* api callbacks */
 	//ot->invoke = mesh_extrude_region_invoke;
 	ot->exec = edbm_extrude_region_exec;
 	ot->poll = ED_operator_editmesh;
-	
+
 	/* flags */
 	ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 
 	Transform_Properties(ot, P_NO_DEFAULTS | P_MIRROR_DUMMY);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Extrude Verts Operator
+ * \{ */
+
 static int edbm_extrude_verts_exec(bContext *C, wmOperator *op)
 {
 	Object *obedit = CTX_data_edit_object(C);
 	BMEditMesh *em = BKE_editmesh_from_object(obedit);
 
 	edbm_extrude_verts_indiv(em, op, BM_ELEM_SELECT);
-	
+
 	EDBM_update_generic(em, true, true);
-	
+
 	return OPERATOR_FINISHED;
 }
 
@@ -429,11 +451,11 @@ void MESH_OT_extrude_verts_indiv(wmOperatorType *ot)
 	ot->name = "Extrude Only Vertices";
 	ot->idname = "MESH_OT_extrude_verts_indiv";
 	ot->description = "Extrude individual vertices only";
-	
+
 	/* api callbacks */
 	ot->exec = edbm_extrude_verts_exec;
 	ot->poll = ED_operator_editmesh;
-	
+
 	/* flags */
 	ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 
@@ -441,15 +463,21 @@ void MESH_OT_extrude_verts_indiv(wmOperatorType *ot)
 	Transform_Properties(ot, P_NO_DEFAULTS | P_MIRROR_DUMMY);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Extrude Edges Operator
+ * \{ */
+
 static int edbm_extrude_edges_exec(bContext *C, wmOperator *op)
 {
 	Object *obedit = CTX_data_edit_object(C);
 	BMEditMesh *em = BKE_editmesh_from_object(obedit);
 
 	edbm_extrude_edges_indiv(em, op, BM_ELEM_SELECT);
-	
+
 	EDBM_update_generic(em, true, true);
-	
+
 	return OPERATOR_FINISHED;
 }
 
@@ -459,11 +487,11 @@ void MESH_OT_extrude_edges_indiv(wmOperatorType *ot)
 	ot->name = "Extrude Only Edges";
 	ot->idname = "MESH_OT_extrude_edges_indiv";
 	ot->description = "Extrude individual edges only";
-	
+
 	/* api callbacks */
 	ot->exec = edbm_extrude_edges_exec;
 	ot->poll = ED_operator_editmesh;
-	
+
 	/* flags */
 	ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 
@@ -471,15 +499,21 @@ void MESH_OT_extrude_edges_indiv(wmOperatorType *ot)
 	Transform_Properties(ot, P_NO_DEFAULTS | P_MIRROR_DUMMY);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Extrude Faces Operator
+ * \{ */
+
 static int edbm_extrude_faces_exec(bContext *C, wmOperator *op)
 {
 	Object *obedit = CTX_data_edit_object(C);
 	BMEditMesh *em = BKE_editmesh_from_object(obedit);
 
 	edbm_extrude_discrete_faces(em, op, BM_ELEM_SELECT);
-	
+
 	EDBM_update_generic(em, true, true);
-	
+
 	return OPERATOR_FINISHED;
 }
 
@@ -489,18 +523,25 @@ void MESH_OT_extrude_faces_indiv(wmOperatorType *ot)
 	ot->name = "Extrude Individual Faces";
 	ot->idname = "MESH_OT_extrude_faces_indiv";
 	ot->description = "Extrude individual faces only";
-	
+
 	/* api callbacks */
 	ot->exec = edbm_extrude_faces_exec;
 	ot->poll = ED_operator_editmesh;
-	
+
 	/* flags */
 	ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 
 	Transform_Properties(ot, P_NO_DEFAULTS | P_MIRROR_DUMMY);
 }
 
-/* *************** add-click-mesh (extrude) operator ************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Extrude Operator
+ *
+ * Add-click-mesh (extrude) operator.
+ * \{ */
+
 static int edbm_dupli_extrude_cursor_invoke(bContext *C, wmOperator *op, const wmEvent *event)
 {
 	ViewContext vc;
@@ -521,7 +562,7 @@ static int edbm_dupli_extrude_cursor_invoke(bContext *C, wmOperator *op, const w
 
 	zero_v3(center);
 	verts_len = 0;
-	
+
 	BM_ITER_MESH (v1, &iter, vc.em->bm, BM_VERTS_OF_MESH) {
 		if (BM_elem_flag_test(v1, BM_ELEM_SELECT)) {
 			add_v3_v3(center, v1->co);
@@ -584,7 +625,7 @@ static int edbm_dupli_extrude_cursor_invoke(bContext *C, wmOperator *op, const w
 			cross_v3_v3v3(nor, view_vec, cross);
 			normalize_v3(nor);
 		}
-		
+
 		/* center */
 		copy_v3_v3(ofs, center);
 
@@ -593,7 +634,7 @@ static int edbm_dupli_extrude_cursor_invoke(bContext *C, wmOperator *op, const w
 		mul_m4_v3(vc.obedit->imat, ofs); // back in object space
 
 		sub_v3_v3(ofs, center);
-		
+
 		/* calculate rotation */
 		unit_m3(mat);
 		if (done) {
@@ -616,7 +657,7 @@ static int edbm_dupli_extrude_cursor_invoke(bContext *C, wmOperator *op, const w
 				axis_angle_to_mat3(mat, axis, angle);
 			}
 		}
-		
+
 		if (rot_src) {
 			EDBM_op_callf(vc.em, op, "rotate verts=%hv cent=%v matrix=%m3",
 			              BM_ELEM_SELECT, center, mat);
@@ -641,7 +682,7 @@ static int edbm_dupli_extrude_cursor_invoke(bContext *C, wmOperator *op, const w
 		ED_view3d_win_to_3d_int(vc.v3d, vc.ar, center, event->mval, center);
 
 		mul_m4_v3(vc.obedit->imat, center); // back in object space
-		
+
 		EDBM_op_init(vc.em, &bmop, op, "create_vert co=%v", center);
 		BMO_op_exec(vc.em->bm, &bmop);
 
@@ -673,17 +714,22 @@ void MESH_OT_dupli_extrude_cursor(wmOperatorType *ot)
 	ot->name = "Duplicate or Extrude to Cursor";
 	ot->idname = "MESH_OT_dupli_extrude_cursor";
 	ot->description = "Duplicate and extrude selected vertices, edges or faces towards the mouse cursor";
-	
+
 	/* api callbacks */
 	ot->invoke = edbm_dupli_extrude_cursor_invoke;
 	ot->poll = ED_operator_editmesh_region_view3d;
-	
+
 	/* flags */
 	ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 
 	RNA_def_boolean(ot->srna, "rotate_source", true, "Rotate Source", "Rotate initial selection giving better shape");
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Spin Operator
+ * \{ */
 
 static int edbm_spin_exec(bContext *C, wmOperator *op)
 {
@@ -780,6 +826,12 @@ void MESH_OT_spin(wmOperatorType *ot)
 
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Screw Operator
+ * \{ */
+
 static int edbm_screw_exec(bContext *C, wmOperator *op)
 {
 	Object *obedit = CTX_data_edit_object(C);
@@ -910,3 +962,5 @@ void MESH_OT_screw(wmOperatorType *ot)
 	RNA_def_float_vector(ot->srna, "axis", 3, NULL, -1.0f, 1.0f,
 	                     "Axis", "Axis in global view space", -1.0f, 1.0f);
 }
+
+/** \} */
diff --git a/source/blender/editors/mesh/editmesh_path.c b/source/blender/editors/mesh/editmesh_path.c
index a85d2425b3c..bf5a7e3a053 100644
--- a/source/blender/editors/mesh/editmesh_path.c
+++ b/source/blender/editors/mesh/editmesh_path.c
@@ -61,6 +61,10 @@
 
 #include "mesh_intern.h"  /* own include */
 
+/* -------------------------------------------------------------------- */
+/** \name Path Select Struct & Properties
+ * \{ */
+
 struct PathSelectParams {
 	bool track_active;  /* ensure the active element is the last selected item (handy for picking) */
 	bool use_topology_distance;
@@ -100,8 +104,11 @@ struct UserData {
 	const struct PathSelectParams *op_params;
 };
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
-/* Vert Path */
+/** \name Vert Path
+ * \{ */
 
 /* callbacks */
 static bool verttag_filter_cb(BMVert *v, void *UNUSED(user_data_v))
@@ -204,10 +211,11 @@ static void mouse_mesh_shortest_path_vert(
 	EDBM_update_generic(em, false, false);
 }
 
-
+/** \} */
 
 /* -------------------------------------------------------------------- */
-/* Edge Path */
+/** \name Edge Path
+ * \{ */
 
 /* callbacks */
 static bool edgetag_filter_cb(BMEdge *e, void *UNUSED(user_data_v))
@@ -427,10 +435,11 @@ static void mouse_mesh_shortest_path_edge(
 	EDBM_update_generic(em, false, false);
 }
 
-
+/** \} */
 
 /* -------------------------------------------------------------------- */
-/* Face Path */
+/** \name Face Path
+ * \{ */
 
 /* callbacks */
 static bool facetag_filter_cb(BMFace *f, void *UNUSED(user_data_v))
@@ -478,7 +487,6 @@ static void mouse_mesh_shortest_path_face(
 			        facetag_filter_cb, &user_data);
 		}
 
-
 		if (f_act != f_dst) {
 			if (path) {
 				if (op_params->track_active) {
@@ -539,10 +547,11 @@ static void mouse_mesh_shortest_path_face(
 	EDBM_update_generic(em, false, false);
 }
 
-
+/** \} */
 
 /* -------------------------------------------------------------------- */
-/* Main Operator for vert/edge/face tag */
+/** \name Main Operator for vert/edge/face tag
+ * \{ */
 
 static bool edbm_shortest_path_pick_ex(
         Scene *scene, const struct PathSelectParams *op_params,
@@ -709,9 +718,11 @@ void MESH_OT_shortest_path_pick(wmOperatorType *ot)
 	RNA_def_property_flag(prop, PROP_HIDDEN | PROP_SKIP_SAVE);
 }
 
+/** \} */
 
 /* -------------------------------------------------------------------- */
-/* Select path between existing selection */
+/** \name Select Path Between Existing Selection
+ * \{ */
 
 static int edbm_shortest_path_select_exec(bContext *C, wmOperator *op)
 {
@@ -796,3 +807,5 @@ void MESH_OT_shortest_path_select(wmOperatorType *ot)
 	/* properties */
 	path_select_properties(ot);
 }
+
+/** \} */
diff --git a/source/blender/editors/mesh/editmesh_utils.c b/source/blender/editors/mesh/editmesh_utils.c
index 5595ca05065..d25304cef89 100644
--- a/source/blender/editors/mesh/editmesh_utils.c
+++ b/source/blender/editors/mesh/editmesh_utils.c
@@ -63,8 +63,14 @@
 
 #include "mesh_intern.h"  /* own include */
 
-/* mesh backup implementation. This would greatly benefit from some sort of binary diffing
- * just as the undo stack would. So leaving this as an interface for further work */
+/* -------------------------------------------------------------------- */
+/** \name Redo API
+ * \{ */
+
+/* Mesh backup implementation.
+ * This would greatly benefit from some sort of binary diffing
+ * just as the undo stack would.
+ * So leaving this as an interface for further work */
 
 BMBackup EDBM_redo_state_store(BMEditMesh *em)
 {
@@ -76,8 +82,9 @@ BMBackup EDBM_redo_state_store(BMEditMesh *em)
 void EDBM_redo_state_restore(BMBackup backup, BMEditMesh *em, int recalctess)
 {
 	BMesh *tmpbm;
-	if (!em || !backup.bmcopy)
+	if (!em || !backup.bmcopy) {
 		return;
+	}
 
 	BM_mesh_data_free(em->bm);
 	tmpbm = BM_mesh_copy(backup.bmcopy);
@@ -85,8 +92,9 @@ void EDBM_redo_state_restore(BMBackup backup, BMEditMesh *em, int recalctess)
 	MEM_freeN(tmpbm);
 	tmpbm = NULL;
 
-	if (recalctess)
+	if (recalctess) {
 		BKE_editmesh_tessface_calc(em);
+	}
 }
 
 void EDBM_redo_state_free(BMBackup *backup, BMEditMesh *em, int recalctess)
@@ -99,68 +107,21 @@ void EDBM_redo_state_free(BMBackup *backup, BMEditMesh *em, int recalctess)
 		BM_mesh_data_free(backup->bmcopy);
 	}
 
-	if (backup->bmcopy)
+	if (backup->bmcopy) {
 		MEM_freeN(backup->bmcopy);
+	}
 	backup->bmcopy = NULL;
 
-	if (recalctess && em)
+	if (recalctess && em) {
 		BKE_editmesh_tessface_calc(em);
-}
-
-void EDBM_mesh_normals_update(BMEditMesh *em)
-{
-	BM_mesh_normals_update(em->bm);
-}
-
-void EDBM_mesh_clear(BMEditMesh *em)
-{
-	/* clear bmesh */
-	BM_mesh_clear(em->bm);
-	
-	/* free derived meshes */
-	BKE_editmesh_free_derivedmesh(em);
-	
-	/* free tessellation data */
-	em->tottri = 0;
-	if (em->looptris) {
-		MEM_freeN(em->looptris);
-		em->looptris = NULL;
 	}
 }
 
-void EDBM_stats_update(BMEditMesh *em)
-{
-	const char iter_types[3] = {BM_VERTS_OF_MESH,
-	                            BM_EDGES_OF_MESH,
-	                            BM_FACES_OF_MESH};
-
-	BMIter iter;
-	BMElem *ele;
-	int *tots[3];
-	int i;
+/** \} */
 
-	tots[0] = &em->bm->totvertsel;
-	tots[1] = &em->bm->totedgesel;
-	tots[2] = &em->bm->totfacesel;
-	
-	em->bm->totvertsel = em->bm->totedgesel = em->bm->totfacesel = 0;
-
-	for (i = 0; i < 3; i++) {
-		ele = BM_iter_new(&iter, em->bm, iter_types[i], NULL);
-		for ( ; ele; ele = BM_iter_step(&iter)) {
-			if (BM_elem_flag_test(ele, BM_ELEM_SELECT)) {
-				(*tots[i])++;
-			}
-		}
-	}
-}
-
-DerivedMesh *EDBM_mesh_deform_dm_get(BMEditMesh *em)
-{
-	return ((em->derivedFinal != NULL) &&
-	        (em->derivedFinal->type == DM_TYPE_EDITBMESH) &&
-	        (em->derivedFinal->deformedOnly != false)) ? em->derivedFinal : NULL;
-}
+/* -------------------------------------------------------------------- */
+/** \name BMesh Operator (BMO) API Wrapper
+ * \{ */
 
 bool EDBM_op_init(BMEditMesh *em, BMOperator *bmop, wmOperator *op, const char *fmt, ...)
 {
@@ -174,9 +135,10 @@ bool EDBM_op_init(BMEditMesh *em, BMOperator *bmop, wmOperator *op, const char *
 		va_end(list);
 		return false;
 	}
-	
-	if (!em->emcopy)
+
+	if (!em->emcopy) {
 		em->emcopy = BKE_editmesh_copy(em);
+	}
 	em->emcopyusers++;
 
 	va_end(list);
@@ -184,12 +146,11 @@ bool EDBM_op_init(BMEditMesh *em, BMOperator *bmop, wmOperator *op, const char *
 	return true;
 }
 
-
 /* returns 0 on error, 1 on success.  executes and finishes a bmesh operator */
 bool EDBM_op_finish(BMEditMesh *em, BMOperator *bmop, wmOperator *op, const bool do_report)
 {
 	const char *errmsg;
-	
+
 	BMO_op_finish(em->bm, bmop);
 
 	if (BMO_error_get(em->bm, &errmsg, NULL)) {
@@ -244,8 +205,9 @@ bool EDBM_op_callf(BMEditMesh *em, wmOperator *op, const char *fmt, ...)
 		return false;
 	}
 
-	if (!em->emcopy)
+	if (!em->emcopy) {
 		em->emcopy = BKE_editmesh_copy(em);
+	}
 	em->emcopyusers++;
 
 	BMO_op_exec(bm, &bmop);
@@ -254,9 +216,10 @@ bool EDBM_op_callf(BMEditMesh *em, wmOperator *op, const char *fmt, ...)
 	return EDBM_op_finish(em, &bmop, op, true);
 }
 
-bool EDBM_op_call_and_selectf(BMEditMesh *em, wmOperator *op,
-                              const char *select_slot_out, const bool select_extend,
-                              const char *fmt, ...)
+bool EDBM_op_call_and_selectf(
+        BMEditMesh *em, wmOperator *op,
+        const char *select_slot_out, const bool select_extend,
+        const char *fmt, ...)
 {
 	BMOpSlot *slot_select_out;
 	BMesh *bm = em->bm;
@@ -272,8 +235,9 @@ bool EDBM_op_call_and_selectf(BMEditMesh *em, wmOperator *op,
 		return false;
 	}
 
-	if (!em->emcopy)
+	if (!em->emcopy) {
 		em->emcopy = BKE_editmesh_copy(em);
+	}
 	em->emcopyusers++;
 
 	BMO_op_exec(bm, &bmop);
@@ -305,8 +269,9 @@ bool EDBM_op_call_silentf(BMEditMesh *em, const char *fmt, ...)
 		return false;
 	}
 
-	if (!em->emcopy)
+	if (!em->emcopy) {
 		em->emcopy = BKE_editmesh_copy(em);
+	}
 	em->emcopyusers++;
 
 	BMO_op_exec(bm, &bmop);
@@ -315,20 +280,13 @@ bool EDBM_op_call_silentf(BMEditMesh *em, const char *fmt, ...)
 	return EDBM_op_finish(em, &bmop, NULL, false);
 }
 
-void EDBM_selectmode_to_scene(bContext *C)
-{
-	Scene *scene = CTX_data_scene(C);
-	Object *obedit = CTX_data_edit_object(C);
-	BMEditMesh *em = BKE_editmesh_from_object(obedit);
-
-	if (!em)
-		return;
+/** \} */
 
-	scene->toolsettings->selectmode = em->selectmode;
-
-	/* Request redraw of header buttons (to show new select mode) */
-	WM_event_add_notifier(C, NC_SCENE | ND_TOOLSETTINGS, scene);
-}
+/* -------------------------------------------------------------------- */
+/** \name Edit BMesh API
+ *
+ * Make/Clear/Free functions.
+ * \{ */
 
 void EDBM_mesh_make(Object *ob, const int select_mode, const bool add_key_index)
 {
@@ -412,6 +370,22 @@ void EDBM_mesh_load(Object *ob)
 #endif
 }
 
+void EDBM_mesh_clear(BMEditMesh *em)
+{
+	/* clear bmesh */
+	BM_mesh_clear(em->bm);
+
+	/* free derived meshes */
+	BKE_editmesh_free_derivedmesh(em);
+
+	/* free tessellation data */
+	em->tottri = 0;
+	if (em->looptris) {
+		MEM_freeN(em->looptris);
+		em->looptris = NULL;
+	}
+}
+
 /**
  * Should only be called on the active editmesh, otherwise call #BKE_editmesh_free
  */
@@ -426,6 +400,28 @@ void EDBM_mesh_free(BMEditMesh *em)
 	BKE_editmesh_free(em);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Selection Utilities
+ * \{ */
+
+void EDBM_selectmode_to_scene(bContext *C)
+{
+	Scene *scene = CTX_data_scene(C);
+	Object *obedit = CTX_data_edit_object(C);
+	BMEditMesh *em = BKE_editmesh_from_object(obedit);
+
+	if (!em) {
+		return;
+	}
+
+	scene->toolsettings->selectmode = em->selectmode;
+
+	/* Request redraw of header buttons (to show new select mode) */
+	WM_event_add_notifier(C, NC_SCENE | ND_TOOLSETTINGS, scene);
+}
+
 void EDBM_selectmode_flush_ex(BMEditMesh *em, const short selectmode)
 {
 	BM_mesh_select_mode_flush_ex(em->bm, selectmode);
@@ -443,7 +439,6 @@ void EDBM_deselect_flush(BMEditMesh *em)
 	BM_mesh_deselect_flush(em->bm);
 }
 
-
 void EDBM_select_flush(BMEditMesh *em)
 {
 	/* function below doesnt use. just do this to keep the values in sync */
@@ -456,9 +451,10 @@ void EDBM_select_more(BMEditMesh *em, const bool use_face_step)
 	BMOperator bmop;
 	const bool use_faces = (em->selectmode == SCE_SELECT_FACE);
 
-	BMO_op_initf(em->bm, &bmop, BMO_FLAG_DEFAULTS,
-	             "region_extend geom=%hvef use_contract=%b use_faces=%b use_face_step=%b",
-	             BM_ELEM_SELECT, false, use_faces, use_face_step);
+	BMO_op_initf(
+	        em->bm, &bmop, BMO_FLAG_DEFAULTS,
+	        "region_extend geom=%hvef use_contract=%b use_faces=%b use_face_step=%b",
+	        BM_ELEM_SELECT, false, use_faces, use_face_step);
 	BMO_op_exec(em->bm, &bmop);
 	/* don't flush selection in edge/vertex mode  */
 	BMO_slot_buffer_hflag_enable(em->bm, bmop.slots_out, "geom.out", BM_ALL_NOLOOP, BM_ELEM_SELECT, use_faces ? true : false);
@@ -472,9 +468,10 @@ void EDBM_select_less(BMEditMesh *em, const bool use_face_step)
 	BMOperator bmop;
 	const bool use_faces = (em->selectmode == SCE_SELECT_FACE);
 
-	BMO_op_initf(em->bm, &bmop, BMO_FLAG_DEFAULTS,
-	             "region_extend geom=%hvef use_contract=%b use_faces=%b use_face_step=%b",
-	             BM_ELEM_SELECT, true, use_faces, use_face_step);
+	BMO_op_initf(
+	        em->bm, &bmop, BMO_FLAG_DEFAULTS,
+	        "region_extend geom=%hvef use_contract=%b use_faces=%b use_face_step=%b",
+	        BM_ELEM_SELECT, true, use_faces, use_face_step);
 	BMO_op_exec(em->bm, &bmop);
 	/* don't flush selection in edge/vertex mode  */
 	BMO_slot_buffer_hflag_disable(em->bm, bmop.slots_out, "geom.out", BM_ALL_NOLOOP, BM_ELEM_SELECT, use_faces ? true : false);
@@ -496,6 +493,12 @@ void EDBM_flag_enable_all(BMEditMesh *em, const char hflag)
 	BM_mesh_elem_hflag_enable_all(em->bm, BM_VERT | BM_EDGE | BM_FACE, hflag, true);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name UV Vertex Map API
+ * \{ */
+
 /**
  * Return a new UVVertMap from the editmesh
  */
@@ -519,7 +522,7 @@ UvVertMap *BM_uv_vert_map_create(
 	BLI_buffer_declare_static(vec2f, tf_uv_buf, BLI_BUFFER_NOP, BM_DEFAULT_NGON_STACK_SIZE);
 
 	BM_mesh_elem_index_ensure(bm, BM_VERT | BM_FACE);
-	
+
 	totfaces = bm->totface;
 	totverts = bm->totvert;
 	totuv = 0;
@@ -549,7 +552,7 @@ UvVertMap *BM_uv_vert_map_create(
 		BKE_mesh_uv_vert_map_free(vmap);
 		return NULL;
 	}
-	
+
 	BM_ITER_MESH_INDEX (efa, &iter, bm, BM_FACES_OF_MESH, a) {
 		if ((use_select == false) || BM_elem_flag_test(efa, BM_ELEM_SELECT)) {
 			float (*tf_uv)[2];
@@ -562,7 +565,7 @@ UvVertMap *BM_uv_vert_map_create(
 				buf->tfindex = i;
 				buf->f = a;
 				buf->separate = 0;
-				
+
 				buf->next = vmap->vert[BM_elem_index_get(l->v)];
 				vmap->vert[BM_elem_index_get(l->v)] = buf;
 				buf++;
@@ -578,7 +581,7 @@ UvVertMap *BM_uv_vert_map_create(
 			}
 		}
 	}
-	
+
 	/* sort individual uvs for each vert */
 	BM_ITER_MESH_INDEX (ev, &iter, bm, BM_VERTS_OF_MESH, a) {
 		UvMapVert *newvlist = NULL, *vlist = vmap->vert[a];
@@ -593,11 +596,11 @@ UvVertMap *BM_uv_vert_map_create(
 
 			efa = BM_face_at_index(bm, v->f);
 			/* tf = CustomData_bmesh_get(&bm->pdata, efa->head.data, CD_MTEXPOLY); */ /* UNUSED */
-			
+
 			l = BM_iter_at_index(bm, BM_LOOPS_OF_FACE, efa, v->tfindex);
 			luv = BM_ELEM_CD_GET_VOID_P(l, cd_loop_uv_offset);
 			uv = luv->uv;
-			
+
 			lastv = NULL;
 			iterv = vlist;
 
@@ -605,11 +608,11 @@ UvVertMap *BM_uv_vert_map_create(
 				next = iterv->next;
 				efa = BM_face_at_index(bm, iterv->f);
 				/* tf = CustomData_bmesh_get(&bm->pdata, efa->head.data, CD_MTEXPOLY); */ /* UNUSED */
-				
+
 				l = BM_iter_at_index(bm, BM_LOOPS_OF_FACE, efa, iterv->tfindex);
 				luv = BM_ELEM_CD_GET_VOID_P(l, cd_loop_uv_offset);
 				uv2 = luv->uv;
-				
+
 				sub_v2_v2v2(uvdiff, uv2, uv);
 
 				if (fabsf(uvdiff[0]) < limit[0] && fabsf(uvdiff[1]) < limit[1] &&
@@ -642,13 +645,11 @@ UvVertMap *BM_uv_vert_map_create(
 	return vmap;
 }
 
-
 UvMapVert *BM_uv_vert_map_at_index(UvVertMap *vmap, unsigned int v)
 {
 	return vmap->vert[v];
 }
 
-
 /* A specialized vert map used by stitch operator */
 UvElementMap *BM_uv_element_map_create(
         BMesh *bm,
@@ -906,23 +907,30 @@ void BM_uv_element_map_free(UvElementMap *element_map)
 
 UvElement *BM_uv_element_get(UvElementMap *map, BMFace *efa, BMLoop *l)
 {
-	UvElement *element;
-
-	element = map->vert[BM_elem_index_get(l->v)];
-
-	for (; element; element = element->next)
-		if (element->l->f == efa)
+	for (UvElement *element = map->vert[BM_elem_index_get(l->v)];
+	     element;
+	     element = element->next)
+	{
+		if (element->l->f == efa) {
 			return element;
+		}
+	}
 
 	return NULL;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Data Layer Checks
+ * \{ */
+
 /* last_sel, use em->act_face otherwise get the last selected face in the editselections
  * at the moment, last_sel is mainly useful for making sure the space image dosnt flicker */
 BMFace *EDBM_uv_active_face_get(BMEditMesh *em, const bool sloppy, const bool selected, MTexPoly **r_tf)
 {
 	BMFace *efa = NULL;
-	
+
 	if (!EDBM_uv_check(em)) {
 		return NULL;
 	}
@@ -953,6 +961,12 @@ bool EDBM_vert_color_check(BMEditMesh *em)
 	return em && em->bm->totface && CustomData_has_layer(&em->bm->ldata, CD_MLOOPCOL);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Mirror Cache API
+ * \{ */
+
 static BMVert *cache_mirr_intptr_as_bmvert(intptr_t *index_lookup, int index)
 {
 	intptr_t eve_i = index_lookup[index];
@@ -987,9 +1001,10 @@ static BMVert *cache_mirr_intptr_as_bmvert(intptr_t *index_lookup, int index)
  * \param maxdist  Distance for close point test.
  * \param r_index  Optional array to write into, as an alternative to a customdata layer (length of total verts).
  */
-void EDBM_verts_mirror_cache_begin_ex(BMEditMesh *em, const int axis, const bool use_self, const bool use_select,
-                                      /* extra args */
-                                      const bool use_topology, float maxdist, int *r_index)
+void EDBM_verts_mirror_cache_begin_ex(
+        BMEditMesh *em, const int axis, const bool use_self, const bool use_select,
+        /* extra args */
+        const bool use_topology, float maxdist, int *r_index)
 {
 	Mesh *me = (Mesh *)em->ob->data;
 	BMesh *bm = em->bm;
@@ -1013,8 +1028,9 @@ void EDBM_verts_mirror_cache_begin_ex(BMEditMesh *em, const int axis, const bool
 			em->mirror_cdlayer = CustomData_get_named_layer_index(&bm->vdata, CD_PROP_INT, layer_id);
 		}
 
-		cd_vmirr_offset = CustomData_get_n_offset(&bm->vdata, CD_PROP_INT,
-		                                          em->mirror_cdlayer - CustomData_get_layer_index(&bm->vdata, CD_PROP_INT));
+		cd_vmirr_offset = CustomData_get_n_offset(
+		        &bm->vdata, CD_PROP_INT,
+		        em->mirror_cdlayer - CustomData_get_layer_index(&bm->vdata, CD_PROP_INT));
 
 		bm->vdata.layers[em->mirror_cdlayer].flag |= CD_FLAG_TEMPORARY;
 	}
@@ -1087,14 +1103,16 @@ void EDBM_verts_mirror_cache_begin_ex(BMEditMesh *em, const int axis, const bool
 	}
 }
 
-void EDBM_verts_mirror_cache_begin(BMEditMesh *em, const int axis,
-                                   const bool use_self, const bool use_select,
-                                   const bool use_topology)
+void EDBM_verts_mirror_cache_begin(
+        BMEditMesh *em, const int axis,
+        const bool use_self, const bool use_select,
+        const bool use_topology)
 {
-	EDBM_verts_mirror_cache_begin_ex(em, axis,
-	                                 use_self, use_select,
-	                                 /* extra args */
-	                                 use_topology, BM_SEARCH_MAXDIST_MIRR, NULL);
+	EDBM_verts_mirror_cache_begin_ex(
+	        em, axis,
+	        use_self, use_select,
+	        /* extra args */
+	        use_topology, BM_SEARCH_MAXDIST_MIRR, NULL);
 }
 
 BMVert *EDBM_verts_mirror_get(BMEditMesh *em, BMVert *v)
@@ -1182,6 +1200,11 @@ void EDBM_verts_mirror_apply(BMEditMesh *em, const int sel_from, const int sel_t
 	}
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Hide/Reveal API
+ * \{ */
 
 /* swap is 0 or 1, if 1 it hides not selected */
 void EDBM_mesh_hide(BMEditMesh *em, bool swap)
@@ -1216,17 +1239,18 @@ void EDBM_mesh_hide(BMEditMesh *em, bool swap)
 	 */
 }
 
-
 void EDBM_mesh_reveal(BMEditMesh *em, bool select)
 {
-	const char iter_types[3] = {BM_VERTS_OF_MESH,
-	                            BM_EDGES_OF_MESH,
-	                            BM_FACES_OF_MESH};
+	const char iter_types[3] = {
+		BM_VERTS_OF_MESH,
+		BM_EDGES_OF_MESH,
+		BM_FACES_OF_MESH,
+	};
 
 	const bool sels[3] = {
-	    (em->selectmode & SCE_SELECT_VERTEX) != 0,
-	    (em->selectmode & SCE_SELECT_EDGE) != 0,
-	    (em->selectmode & SCE_SELECT_FACE) != 0,
+		(em->selectmode & SCE_SELECT_VERTEX) != 0,
+		(em->selectmode & SCE_SELECT_EDGE) != 0,
+		(em->selectmode & SCE_SELECT_FACE) != 0,
 	};
 	int i;
 
@@ -1266,6 +1290,46 @@ void EDBM_mesh_reveal(BMEditMesh *em, bool select)
 	EDBM_mesh_normals_update(em);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Update API
+ * \{ */
+
+void EDBM_mesh_normals_update(BMEditMesh *em)
+{
+	BM_mesh_normals_update(em->bm);
+}
+
+void EDBM_stats_update(BMEditMesh *em)
+{
+	const char iter_types[3] = {
+		BM_VERTS_OF_MESH,
+		BM_EDGES_OF_MESH,
+		BM_FACES_OF_MESH,
+	};
+
+	BMIter iter;
+	BMElem *ele;
+	int *tots[3];
+	int i;
+
+	tots[0] = &em->bm->totvertsel;
+	tots[1] = &em->bm->totedgesel;
+	tots[2] = &em->bm->totfacesel;
+
+	em->bm->totvertsel = em->bm->totedgesel = em->bm->totfacesel = 0;
+
+	for (i = 0; i < 3; i++) {
+		ele = BM_iter_new(&iter, em->bm, iter_types[i], NULL);
+		for ( ; ele; ele = BM_iter_step(&iter)) {
+			if (BM_elem_flag_test(ele, BM_ELEM_SELECT)) {
+				(*tots[i])++;
+			}
+		}
+	}
+}
+
 /* so many tools call these that we better make it a generic function.
  */
 void EDBM_update_generic(BMEditMesh *em, const bool do_tessface, const bool is_destructive)
@@ -1301,15 +1365,41 @@ void EDBM_update_generic(BMEditMesh *em, const bool do_tessface, const bool is_d
 #endif
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Data Access
+ * \{ */
+
+DerivedMesh *EDBM_mesh_deform_dm_get(BMEditMesh *em)
+{
+	return ((em->derivedFinal != NULL) &&
+	        (em->derivedFinal->type == DM_TYPE_EDITBMESH) &&
+	        (em->derivedFinal->deformedOnly != false)) ? em->derivedFinal : NULL;
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Operator Helpers
+ * \{ */
+
 /* poll call for mesh operators requiring a view3d context */
 int EDBM_view3d_poll(bContext *C)
 {
-	if (ED_operator_editmesh(C) && ED_operator_view3d_active(C))
+	if (ED_operator_editmesh(C) && ED_operator_view3d_active(C)) {
 		return 1;
+	}
 
 	return 0;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name BMesh Element API
+ * \{ */
+
 BMElem *EDBM_elem_from_selectmode(BMEditMesh *em, BMVert *eve, BMEdge *eed, BMFace *efa)
 {
 	BMElem *ele = NULL;
@@ -1374,22 +1464,19 @@ BMElem *EDBM_elem_from_index_any(BMEditMesh *em, int index)
 	return NULL;
 }
 
-/* -------------------------------------------------------------------- */
-/* BMBVH functions */
-// XXX
-#if 0 //BMESH_TODO: not implemented yet
-int BMBVH_VertVisible(BMBVHTree *tree, BMEdge *e, RegionView3D *r3d)
-{
+/** \} */
 
-}
-#endif
+/* -------------------------------------------------------------------- */
+/** \name BMesh BVH API
+ * \{ */
 
 static BMFace *edge_ray_cast(struct BMBVHTree *tree, const float co[3], const float dir[3], float *r_hitout, BMEdge *e)
 {
 	BMFace *f = BKE_bmbvh_ray_cast(tree, co, dir, 0.0f, NULL, r_hitout, NULL);
 
-	if (f && BM_edge_in_face(e, f))
+	if (f && BM_edge_in_face(e, f)) {
 		return NULL;
+	}
 
 	return f;
 }
@@ -1408,8 +1495,10 @@ bool BMBVH_EdgeVisible(struct BMBVHTree *tree, BMEdge *e, ARegion *ar, View3D *v
 	float origin[3], invmat[4][4];
 	float epsilon = 0.01f;
 	float end[3];
-	const float mval_f[2] = {ar->winx / 2.0f,
-	                         ar->winy / 2.0f};
+	const float mval_f[2] = {
+		ar->winx / 2.0f,
+		ar->winy / 2.0f,
+	};
 
 	ED_view3d_win_to_segment(ar, v3d, mval_f, origin, end, false);
 
@@ -1445,12 +1534,17 @@ bool BMBVH_EdgeVisible(struct BMBVHTree *tree, BMEdge *e, ARegion *ar, View3D *v
 
 	/* do three samplings: left, middle, right */
 	f = edge_ray_cast(tree, co1, dir1, NULL, e);
-	if (f && !edge_ray_cast(tree, co2, dir2, NULL, e))
+	if (f && !edge_ray_cast(tree, co2, dir2, NULL, e)) {
 		return true;
-	else if (f && !edge_ray_cast(tree, co3, dir3, NULL, e))
+	}
+	else if (f && !edge_ray_cast(tree, co3, dir3, NULL, e)) {
 		return true;
-	else if (!f)
+	}
+	else if (!f) {
 		return true;
+	}
 
 	return false;
 }
+
+/** \} */