Merge branch 'master' into soc-2021-uv-edge-select-supportsoc-2021-uv-edge-select-support

1 files changed, 81 insertions, 5 deletions

diff --git a/source/blender/bmesh/intern/bmesh_marking.h b/source/blender/bmesh/intern/bmesh_marking.h
index 99feae1d66c..72b520cc72c 100644
--- a/source/blender/bmesh/intern/bmesh_marking.h
+++ b/source/blender/bmesh/intern/bmesh_marking.h
@@ -36,14 +36,20 @@ typedef enum eBMSelectionFlushFLags {
                                     BM_SELECT_LEN_FLUSH_RECALC_FACE),
 } eBMSelectionFlushFLags;
 
-/* geometry hiding code */
+/* Geometry hiding code. */
+
 #define BM_elem_hide_set(bm, ele, hide) _bm_elem_hide_set(bm, &(ele)->head, hide)
 void _bm_elem_hide_set(BMesh *bm, BMHeader *head, const bool hide);
 void BM_vert_hide_set(BMVert *v, const bool hide);
 void BM_edge_hide_set(BMEdge *e, const bool hide);
 void BM_face_hide_set(BMFace *f, const bool hide);
 
-/* Selection code */
+/* Selection code. */
+
+/**
+ * \note use BM_elem_flag_test(ele, BM_ELEM_SELECT) to test selection
+ * \note by design, this will not touch the editselection history stuff
+ */
 void BM_elem_select_set(BMesh *bm, BMElem *ele, const bool select);
 
 void BM_mesh_elem_hflag_enable_test(BMesh *bm,
@@ -68,24 +74,70 @@ void BM_mesh_elem_hflag_disable_all(BMesh *bm,
                                     const char hflag,
                                     const bool respecthide);
 
-/* Individual element select functions, BM_elem_select_set is a shortcut for these
+/* Individual element select functions, #BM_elem_select_set is a shortcut for these
  * that automatically detects which one to use. */
+
+/**
+ * \brief Select Vert
+ *
+ * Changes selection state of a single vertex
+ * in a mesh
+ */
 void BM_vert_select_set(BMesh *bm, BMVert *v, const bool select);
+/**
+ * \brief Select Edge
+ *
+ * Changes selection state of a single edge in a mesh.
+ */
 void BM_edge_select_set(BMesh *bm, BMEdge *e, const bool select);
+/**
+ * \brief Select Face
+ *
+ * Changes selection state of a single
+ * face in a mesh.
+ */
 void BM_face_select_set(BMesh *bm, BMFace *f, const bool select);
 
-/* lower level functions which don't do flushing */
+/* Lower level functions which don't do flushing. */
+
 void BM_edge_select_set_noflush(BMesh *bm, BMEdge *e, const bool select);
 void BM_face_select_set_noflush(BMesh *bm, BMFace *f, const bool select);
 
+/**
+ * \brief Select Mode Clean
+ *
+ * Remove isolated selected elements when in a mode doesn't support them.
+ * eg: in edge-mode a selected vertex must be connected to a selected edge.
+ *
+ * \note this could be made a part of #BM_mesh_select_mode_flush_ex
+ */
 void BM_mesh_select_mode_clean_ex(BMesh *bm, const short selectmode);
 void BM_mesh_select_mode_clean(BMesh *bm);
 
+/**
+ * Select Mode Set
+ *
+ * Sets the selection mode for the bmesh,
+ * updating the selection state.
+ */
 void BM_mesh_select_mode_set(BMesh *bm, int selectmode);
+/**
+ * \brief Select Mode Flush
+ *
+ * Makes sure to flush selections 'upwards'
+ * (ie: all verts of an edge selects the edge and so on).
+ * This should only be called by system and not tool authors.
+ */
 void BM_mesh_select_mode_flush_ex(BMesh *bm, const short selectmode, eBMSelectionFlushFLags flags);
 void BM_mesh_select_mode_flush(BMesh *bm);
 
+/**
+ * Mode independent de-selection flush (up/down).
+ */
 void BM_mesh_deselect_flush(BMesh *bm);
+/**
+ * Mode independent selection flush (up/down).
+ */
 void BM_mesh_select_flush(BMesh *bm);
 
 int BM_mesh_elem_hflag_count_enabled(BMesh *bm,
@@ -97,15 +149,30 @@ int BM_mesh_elem_hflag_count_disabled(BMesh *bm,
                                       const char hflag,
                                       const bool respecthide);
 
-/* edit selection stuff */
+/* Edit selection stuff. */
+
 void BM_mesh_active_face_set(BMesh *bm, BMFace *f);
 BMFace *BM_mesh_active_face_get(BMesh *bm, const bool is_sloppy, const bool is_selected);
 BMEdge *BM_mesh_active_edge_get(BMesh *bm);
 BMVert *BM_mesh_active_vert_get(BMesh *bm);
 BMElem *BM_mesh_active_elem_get(BMesh *bm);
 
+/**
+ * Generic way to get data from an #BMEditSelection type
+ * These functions were written to be used by the Modifier widget
+ * when in Rotate about active mode, but can be used anywhere.
+ *
+ * - #BM_editselection_center
+ * - #BM_editselection_normal
+ * - #BM_editselection_plane
+ */
 void BM_editselection_center(BMEditSelection *ese, float r_center[3]);
 void BM_editselection_normal(BMEditSelection *ese, float r_normal[3]);
+/**
+ * Calculate a plane that is right angles to the edge/vert/faces normal
+ * also make the plane run along an axis that is related to the geometry,
+ * because this is used for the gizmos Y axis.
+ */
 void BM_editselection_plane(BMEditSelection *ese, float r_plane[3]);
 
 #define BM_select_history_check(bm, ele) _bm_select_history_check(bm, &(ele)->head)
@@ -131,9 +198,18 @@ void _bm_select_history_store_after_notest(BMesh *bm, BMEditSelection *ese_ref,
 
 void BM_select_history_validate(BMesh *bm);
 void BM_select_history_clear(BMesh *bm);
+/**
+ * Get the active mesh element (with active-face fallback).
+ */
 bool BM_select_history_active_get(BMesh *bm, struct BMEditSelection *ese);
+/**
+ * Return a map from #BMVert/#BMEdge/#BMFace -> #BMEditSelection.
+ */
 struct GHash *BM_select_history_map_create(BMesh *bm);
 
+/**
+ * Map arguments may all be the same pointer.
+ */
 void BM_select_history_merge_from_targetmap(
     BMesh *bm, GHash *vert_map, GHash *edge_map, GHash *face_map, const bool use_chain);