Cleanup: move public doc-strings into headers for 'bmesh'

Some minor improvements to doc-strings too.

Ref T92709

1 files changed, 0 insertions, 287 deletions

diff --git a/source/blender/bmesh/intern/bmesh_core.c b/source/blender/bmesh/intern/bmesh_core.c
index e72c689ddfb..1d7d10de96f 100644
--- a/source/blender/bmesh/intern/bmesh_core.c
+++ b/source/blender/bmesh/intern/bmesh_core.c
@@ -52,9 +52,6 @@
 
 #endif
 
-/**
- * \brief Main function for creating a new vertex.
- */
 BMVert *BM_vert_create(BMesh *bm,
                        const float co[3],
                        const BMVert *v_example,
@@ -137,13 +134,6 @@ BMVert *BM_vert_create(BMesh *bm,
   return v;
 }
 
-/**
- * \brief Main function for creating a new edge.
- *
- * \note Duplicate edges are supported by the API however users should _never_ see them.
- * so unless you need a unique edge or know the edge won't exist,
- * you should call with \a no_double = true.
- */
 BMEdge *BM_edge_create(
     BMesh *bm, BMVert *v1, BMVert *v2, const BMEdge *e_example, const eBMCreateFlag create_flag)
 {
@@ -416,15 +406,6 @@ BLI_INLINE BMFace *bm_face_create__internal(BMesh *bm)
   return f;
 }
 
-/**
- * Main face creation function
- *
- * \param bm: The mesh
- * \param verts: A sorted array of verts size of len
- * \param edges: A sorted array of edges size of len
- * \param len: Length of the face
- * \param create_flag: Options for creating the face
- */
 BMFace *BM_face_create(BMesh *bm,
                        BMVert **verts,
                        BMEdge **edges,
@@ -494,9 +475,6 @@ BMFace *BM_face_create(BMesh *bm,
   return f;
 }
 
-/**
- * Wrapper for #BM_face_create when you don't have an edge array
- */
 BMFace *BM_face_create_verts(BMesh *bm,
                              BMVert **vert_arr,
                              const int len,
@@ -520,12 +498,6 @@ BMFace *BM_face_create_verts(BMesh *bm,
 
 #ifndef NDEBUG
 
-/**
- * Check the element is valid.
- *
- * BMESH_TODO, when this raises an error the output is incredibly confusing.
- * need to have some nice way to print/debug what the heck's going on.
- */
 int bmesh_elem_check(void *element, const char htype)
 {
   BMHeader *head = element;
@@ -833,10 +805,6 @@ static void bm_kill_only_loop(BMesh *bm, BMLoop *l)
   BLI_mempool_free(bm->lpool, l);
 }
 
-/**
- * kills all edges associated with \a f, along with any other faces containing
- * those edges
- */
 void BM_face_edges_kill(BMesh *bm, BMFace *f)
 {
   BMEdge **edges = BLI_array_alloca(edges, f->len);
@@ -854,10 +822,6 @@ void BM_face_edges_kill(BMesh *bm, BMFace *f)
   }
 }
 
-/**
- * kills all verts associated with \a f, along with any other faces containing
- * those vertices
- */
 void BM_face_verts_kill(BMesh *bm, BMFace *f)
 {
   BMVert **verts = BLI_array_alloca(verts, f->len);
@@ -875,9 +839,6 @@ void BM_face_verts_kill(BMesh *bm, BMFace *f)
   }
 }
 
-/**
- * Kills \a f and its loops.
- */
 void BM_face_kill(BMesh *bm, BMFace *f)
 {
 #ifdef USE_BMESH_HOLES
@@ -922,10 +883,6 @@ void BM_face_kill(BMesh *bm, BMFace *f)
   bm_kill_only_face(bm, f);
 }
 
-/**
- * A version of #BM_face_kill which removes edges and verts
- * which have no remaining connected geometry.
- */
 void BM_face_kill_loose(BMesh *bm, BMFace *f)
 {
 #ifdef USE_BMESH_HOLES
@@ -981,9 +938,6 @@ void BM_face_kill_loose(BMesh *bm, BMFace *f)
   bm_kill_only_face(bm, f);
 }
 
-/**
- * kills \a e and all faces that use it.
- */
 void BM_edge_kill(BMesh *bm, BMEdge *e)
 {
   while (e->l) {
@@ -996,9 +950,6 @@ void BM_edge_kill(BMesh *bm, BMEdge *e)
   bm_kill_only_edge(bm, e);
 }
 
-/**
- * kills \a v and all edges that use it.
- */
 void BM_vert_kill(BMesh *bm, BMVert *v)
 {
   while (v->e) {
@@ -1025,15 +976,6 @@ static int UNUSED_FUNCTION(bm_loop_length)(BMLoop *l)
   return i;
 }
 
-/**
- * \brief Loop Reverse
- *
- * Changes the winding order of a face from CW to CCW or vice versa.
- *
- * \param cd_loop_mdisp_offset: Cached result of `CustomData_get_offset(&bm->ldata, CD_MDISPS)`.
- * \param use_loop_mdisp_flip: When set, flip the Z-depth of the mdisp,
- * (use when flipping normals, disable when mirroring, eg: symmetrize).
- */
 void bmesh_kernel_loop_reverse(BMesh *bm,
                                BMFace *f,
                                const int cd_loop_mdisp_offset,
@@ -1192,20 +1134,6 @@ static bool bm_vert_is_manifold_flagged(BMVert *v, const char api_flag)
 
 /* Mid-level Topology Manipulation Functions */
 
-/**
- * \brief Join Connected Faces
- *
- * Joins a collected group of faces into one. Only restriction on
- * the input data is that the faces must be connected to each other.
- *
- * \return The newly created combine BMFace.
- *
- * \note If a pair of faces share multiple edges,
- * the pair of faces will be joined at every edge.
- *
- * \note this is a generic, flexible join faces function,
- * almost everything uses this, including #BM_faces_join_pair
- */
 BMFace *BM_faces_join(BMesh *bm, BMFace **faces, int totface, const bool do_del)
 {
   BMFace *f, *f_new;
@@ -1422,44 +1350,6 @@ static BMFace *bm_face_create__sfme(BMesh *bm, BMFace *f_example)
   return f;
 }
 
-/**
- * \brief Split Face Make Edge (SFME)
- *
- * \warning this is a low level function, most likely you want to use #BM_face_split()
- *
- * Takes as input two vertices in a single face.
- * An edge is created which divides the original face into two distinct regions.
- * One of the regions is assigned to the original face and it is closed off.
- * The second region has a new face assigned to it.
- *
- * \par Examples:
- * <pre>
- *     Before:               After:
- *      +--------+           +--------+
- *      |        |           |        |
- *      |        |           |   f1   |
- *     v1   f1   v2          v1======v2
- *      |        |           |   f2   |
- *      |        |           |        |
- *      +--------+           +--------+
- * </pre>
- *
- * \note the input vertices can be part of the same edge. This will
- * result in a two edged face. This is desirable for advanced construction
- * tools and particularly essential for edge bevel. Because of this it is
- * up to the caller to decide what to do with the extra edge.
- *
- * \note If \a holes is NULL, then both faces will lose
- * all holes from the original face.  Also, you cannot split between
- * a hole vert and a boundary vert; that case is handled by higher-
- * level wrapping functions (when holes are fully implemented, anyway).
- *
- * \note that holes represents which holes goes to the new face, and of
- * course this requires removing them from the existing face first, since
- * you cannot have linked list links inside multiple lists.
- *
- * \return A BMFace pointer
- */
 BMFace *bmesh_kernel_split_face_make_edge(BMesh *bm,
                                           BMFace *f,
                                           BMLoop *l_v1,
@@ -1599,24 +1489,6 @@ BMFace *bmesh_kernel_split_face_make_edge(BMesh *bm,
   return f2;
 }
 
-/**
- * \brief Split Edge Make Vert (SEMV)
- *
- * Takes \a e edge and splits it into two, creating a new vert.
- * \a tv should be one end of \a e : the newly created edge
- * will be attached to that end and is returned in \a r_e.
- *
- * \par Examples:
- *
- * <pre>
- *                     E
- *     Before: OV-------------TV
- *                 E       RE
- *     After:  OV------NV-----TV
- * </pre>
- *
- * \return The newly created BMVert pointer.
- */
 BMVert *bmesh_kernel_split_edge_make_vert(BMesh *bm, BMVert *tv, BMEdge *e, BMEdge **r_e)
 {
   BMLoop *l_next;
@@ -1770,36 +1642,6 @@ BMVert *bmesh_kernel_split_edge_make_vert(BMesh *bm, BMVert *tv, BMEdge *e, BMEd
   return v_new;
 }
 
-/**
- * \brief Join Edge Kill Vert (JEKV)
- *
- * Takes an edge \a e_kill and pointer to one of its vertices \a v_kill
- * and collapses the edge on that vertex.
- *
- * \par Examples:
- *
- * <pre>
- *     Before:    e_old  e_kill
- *              +-------+-------+
- *              |       |       |
- *              v_old   v_kill  v_target
- *
- *     After:           e_old
- *              +---------------+
- *              |               |
- *              v_old           v_target
- * </pre>
- *
- * \par Restrictions:
- * KV is a vertex that must have a valance of exactly two. Furthermore
- * both edges in KV's disk cycle (OE and KE) must be unique (no double edges).
- *
- * \return The resulting edge, NULL for failure.
- *
- * \note This euler has the possibility of creating
- * faces with just 2 edges. It is up to the caller to decide what to do with
- * these faces.
- */
 BMEdge *bmesh_kernel_join_edge_kill_vert(BMesh *bm,
                                          BMEdge *e_kill,
                                          BMVert *v_kill,
@@ -1967,24 +1809,6 @@ BMEdge *bmesh_kernel_join_edge_kill_vert(BMesh *bm,
   return NULL;
 }
 
-/**
- * \brief Join Vert Kill Edge (JVKE)
- *
- * Collapse an edge, merging surrounding data.
- *
- * Unlike #BM_vert_collapse_edge & #bmesh_kernel_join_edge_kill_vert
- * which only handle 2 valence verts,
- * this can handle any number of connected edges/faces.
- *
- * <pre>
- * Before: -> After:
- * +-+-+-+    +-+-+-+
- * | | | |    | \ / |
- * +-+-+-+    +--+--+
- * | | | |    | / \ |
- * +-+-+-+    +-+-+-+
- * </pre>
- */
 BMVert *bmesh_kernel_join_vert_kill_edge(BMesh *bm,
                                          BMEdge *e_kill,
                                          BMVert *v_kill,
@@ -2068,37 +1892,6 @@ BMVert *bmesh_kernel_join_vert_kill_edge(BMesh *bm,
   return v_target;
 }
 
-/**
- * \brief Join Face Kill Edge (JFKE)
- *
- * Takes two faces joined by a single 2-manifold edge and fuses them together.
- * The edge shared by the faces must not be connected to any other edges which have
- * Both faces in its radial cycle
- *
- * \par Examples:
- * <pre>
- *           A                   B
- *      +--------+           +--------+
- *      |        |           |        |
- *      |   f1   |           |   f1   |
- *     v1========v2 = Ok!    v1==V2==v3 == Wrong!
- *      |   f2   |           |   f2   |
- *      |        |           |        |
- *      +--------+           +--------+
- * </pre>
- *
- * In the example A, faces \a f1 and \a f2 are joined by a single edge,
- * and the euler can safely be used.
- * In example B however, \a f1 and \a f2 are joined by multiple edges and will produce an error.
- * The caller in this case should call #bmesh_kernel_join_edge_kill_vert on the extra edges
- * before attempting to fuse \a f1 and \a f2.
- *
- * \note The order of arguments decides whether or not certain per-face attributes are present
- * in the resultant face. For instance vertex winding, material index, smooth flags,
- * etc are inherited from \a f1, not \a f2.
- *
- * \return A BMFace pointer
- */
 BMFace *bmesh_kernel_join_face_kill_edge(BMesh *bm, BMFace *f1, BMFace *f2, BMEdge *e)
 {
   BMLoop *l_iter, *l_f1 = NULL, *l_f2 = NULL;
@@ -2221,11 +2014,6 @@ BMFace *bmesh_kernel_join_face_kill_edge(BMesh *bm, BMFace *f1, BMFace *f2, BMEd
   return f1;
 }
 
-/**
- * Check if splicing vertices would create any double edges.
- *
- * \note assume caller will handle case where verts share an edge.
- */
 bool BM_vert_splice_check_double(BMVert *v_a, BMVert *v_b)
 {
   bool is_double = false;
@@ -2269,18 +2057,6 @@ bool BM_vert_splice_check_double(BMVert *v_a, BMVert *v_b)
   return is_double;
 }
 
-/**
- * \brief Splice Vert
- *
- * Merges two verts into one
- * (\a v_src into \a v_dst, removing \a v_src).
- *
- * \return Success
- *
- * \warning This doesn't work for collapsing edges,
- * where \a v and \a vtarget are connected by an edge
- * (assert checks for this case).
- */
 bool BM_vert_splice(BMesh *bm, BMVert *v_dst, BMVert *v_src)
 {
   BMEdge *e;
@@ -2317,17 +2093,6 @@ BLI_INLINE bool bm_edge_supports_separate(const BMEdge *e)
   return (e->l && e->l->radial_next != e->l);
 }
 
-/**
- * \brief Separate Vert
- *
- * Separates all disjoint fans that meet at a vertex, making a unique
- * vertex for each region. returns an array of all resulting vertices.
- *
- * \note this is a low level function, bm_edge_separate needs to run on edges first
- * or, the faces sharing verts must not be sharing edges for them to split at least.
- *
- * \return Success
- */
 void bmesh_kernel_vert_separate(
     BMesh *bm, BMVert *v, BMVert ***r_vout, int *r_vout_len, const bool copy_select)
 {
@@ -2480,9 +2245,6 @@ static void bmesh_kernel_vert_separate__cleanup(BMesh *bm, LinkNode *edges_separ
   } while ((edges_separate = edges_separate->next));
 }
 
-/**
- * High level function which wraps both #bmesh_kernel_vert_separate and #bmesh_kernel_edge_separate
- */
 void BM_vert_separate(BMesh *bm,
                       BMVert *v,
                       BMEdge **e_in,
@@ -2516,9 +2278,6 @@ void BM_vert_separate(BMesh *bm,
   }
 }
 
-/**
- * A version of #BM_vert_separate which takes a flag.
- */
 void BM_vert_separate_hflag(BMesh *bm,
                             BMVert *v,
                             const char hflag,
@@ -2584,16 +2343,6 @@ void BM_vert_separate_tested_edges(BMesh *UNUSED(bm),
 
 /** \} */
 
-/**
- * \brief Splice Edge
- *
- * Splice two unique edges which share the same two vertices into one edge.
- *  (\a e_src into \a e_dst, removing e_src).
- *
- * \return Success
- *
- * \note Edges must already have the same vertices.
- */
 bool BM_edge_splice(BMesh *bm, BMEdge *e_dst, BMEdge *e_src)
 {
   BMLoop *l;
@@ -2627,17 +2376,6 @@ bool BM_edge_splice(BMesh *bm, BMEdge *e_dst, BMEdge *e_src)
   return true;
 }
 
-/**
- * \brief Separate Edge
- *
- * Separates a single edge into two edge: the original edge and
- * a new edge that has only \a l_sep in its radial.
- *
- * \return Success
- *
- * \note Does nothing if \a l_sep is already the only loop in the
- * edge radial.
- */
 void bmesh_kernel_edge_separate(BMesh *bm, BMEdge *e, BMLoop *l_sep, const bool copy_select)
 {
   BMEdge *e_new;
@@ -2673,15 +2411,6 @@ void bmesh_kernel_edge_separate(BMesh *bm, BMEdge *e, BMLoop *l_sep, const bool
   BM_CHECK_ELEMENT(e);
 }
 
-/**
- * \brief Un-glue Region Make Vert (URMV)
- *
- * Disconnects a face from its vertex fan at loop \a l_sep
- *
- * \return The newly created BMVert
- *
- * \note Will be a no-op and return original vertex if only two edges at that vertex.
- */
 BMVert *bmesh_kernel_unglue_region_make_vert(BMesh *bm, BMLoop *l_sep)
 {
   BMVert *v_new = NULL;
@@ -2744,13 +2473,6 @@ BMVert *bmesh_kernel_unglue_region_make_vert(BMesh *bm, BMLoop *l_sep)
   return v_new;
 }
 
-/**
- * A version of #bmesh_kernel_unglue_region_make_vert that disconnects multiple loops at once.
- * The loops must all share the same vertex, can be in any order
- * and are all moved to use a single new vertex - which is returned.
- *
- * This function handles the details of finding fans boundaries.
- */
 BMVert *bmesh_kernel_unglue_region_make_vert_multi(BMesh *bm, BMLoop **larr, int larr_len)
 {
   BMVert *v_sep = larr[0]->v;
@@ -2931,10 +2653,6 @@ static void bmesh_edge_vert_swap__recursive(BMEdge *e, BMVert *v_dst, BMVert *v_
   } while ((l_iter = l_iter->radial_next) != l_first);
 }
 
-/**
- * This function assumes l_sep is a part of a larger fan which has already been
- * isolated by calling #bmesh_kernel_edge_separate to segregate it radially.
- */
 BMVert *bmesh_kernel_unglue_region_make_vert_multi_isolated(BMesh *bm, BMLoop *l_sep)
 {
   BMVert *v_new = BM_vert_create(bm, l_sep->v->co, l_sep->v, BM_CREATE_NOP);
@@ -2944,11 +2662,6 @@ BMVert *bmesh_kernel_unglue_region_make_vert_multi_isolated(BMesh *bm, BMLoop *l
   return v_new;
 }
 
-/**
- * Avoid calling this where possible,
- * low level function so both face pointers remain intact but point to swapped data.
- * \note must be from the same bmesh.
- */
 void bmesh_face_swap_data(BMFace *f_a, BMFace *f_b)
 {
   BMLoop *l_iter, *l_first;