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

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 78 insertions, 1 deletions

diff --git a/source/blender/blenkernel/BKE_mesh_mapping.h b/source/blender/blenkernel/BKE_mesh_mapping.h
index 0518f303744..acc1628de1d 100644
--- a/source/blender/blenkernel/BKE_mesh_mapping.h
+++ b/source/blender/blenkernel/BKE_mesh_mapping.h
@@ -105,6 +105,11 @@ UvVertMap *BKE_mesh_uv_vert_map_create(const struct MPoly *mpoly,
 UvMapVert *BKE_mesh_uv_vert_map_get_vert(UvVertMap *vmap, unsigned int v);
 void BKE_mesh_uv_vert_map_free(UvVertMap *vmap);
 
+/**
+ * Generates a map where the key is the vertex and the value
+ * is a list of polys that use that vertex as a corner.
+ * The lists are allocated from one memory pool.
+ */
 void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map,
                                    int **r_mem,
                                    const struct MPoly *mpoly,
@@ -112,6 +117,11 @@ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map,
                                    int totvert,
                                    int totpoly,
                                    int totloop);
+/**
+ * Generates a map where the key is the vertex and the value
+ * is a list of loops that use that vertex as a corner.
+ * The lists are allocated from one memory pool.
+ */
 void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map,
                                    int **r_mem,
                                    const struct MPoly *mpoly,
@@ -119,6 +129,11 @@ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map,
                                    int totvert,
                                    int totpoly,
                                    int totloop);
+/**
+ * Generates a map where the key is the edge and the value
+ * is a list of looptris that use that edge.
+ * The lists are allocated from one memory pool.
+ */
 void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map,
                                       int **r_mem,
                                       const struct MVert *mvert,
@@ -127,10 +142,24 @@ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map,
                                       const int totlooptri,
                                       const struct MLoop *mloop,
                                       const int totloop);
+/**
+ * Generates a map where the key is the vertex and the value
+ * is a list of edges that use that vertex as an endpoint.
+ * The lists are allocated from one memory pool.
+ */
 void BKE_mesh_vert_edge_map_create(
     MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, int totvert, int totedge);
+/**
+ * A version of #BKE_mesh_vert_edge_map_create that references connected vertices directly
+ * (not their edges).
+ */
 void BKE_mesh_vert_edge_vert_map_create(
     MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, int totvert, int totedge);
+/**
+ * Generates a map where the key is the edge and the value is a list of loops that use that edge.
+ * Loops indices of a same poly are contiguous and in winding order.
+ * The lists are allocated from one memory pool.
+ */
 void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map,
                                    int **r_mem,
                                    const struct MEdge *medge,
@@ -139,6 +168,11 @@ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map,
                                    const int totpoly,
                                    const struct MLoop *mloop,
                                    const int totloop);
+/**
+ * Generates a map where the key is the edge and the value
+ * is a list of polygons that use that edge.
+ * The lists are allocated from one memory pool.
+ */
 void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map,
                                    int **r_mem,
                                    const struct MEdge *medge,
@@ -147,11 +181,29 @@ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map,
                                    const int totpoly,
                                    const struct MLoop *mloop,
                                    const int totloop);
+/**
+ * This function creates a map so the source-data (vert/edge/loop/poly)
+ * can loop over the destination data (using the destination arrays origindex).
+ *
+ * This has the advantage that it can operate on any data-types.
+ *
+ * \param totsource: The total number of elements that \a final_origindex points to.
+ * \param totfinal: The size of \a final_origindex
+ * \param final_origindex: The size of the final array.
+ *
+ * \note `totsource` could be `totpoly`,
+ *       `totfinal` could be `tottessface` and `final_origindex` its ORIGINDEX custom-data.
+ *       This would allow an MPoly to loop over its tessfaces.
+ */
 void BKE_mesh_origindex_map_create(MeshElemMap **r_map,
                                    int **r_mem,
                                    const int totsource,
                                    const int *final_origindex,
                                    const int totfinal);
+/**
+ * A version of #BKE_mesh_origindex_map_create that takes a looptri array.
+ * Making a poly -> looptri map.
+ */
 void BKE_mesh_origindex_map_create_looptri(MeshElemMap **r_map,
                                            int **r_mem,
                                            const struct MPoly *mpoly,
@@ -212,7 +264,11 @@ typedef bool (*MeshRemapIslandsCalc)(struct MVert *verts,
                                      struct MeshIslandStore *r_island_store);
 
 /* Above vert/UV mapping stuff does not do what we need here, but does things we do not need here.
- * So better keep them separated for now, I think.
+ * So better keep them separated for now, I think. */
+
+/**
+ * Calculate 'generic' UV islands, i.e. based only on actual geometry data (edge seams),
+ * not some UV layers coordinates.
  */
 bool BKE_mesh_calc_islands_loop_poly_edgeseam(struct MVert *verts,
                                               const int totvert,
@@ -224,6 +280,19 @@ bool BKE_mesh_calc_islands_loop_poly_edgeseam(struct MVert *verts,
                                               const int totloop,
                                               MeshIslandStore *r_island_store);
 
+/**
+ * Calculate UV islands.
+ *
+ * \note If no MLoopUV layer is passed, we only consider edges tagged as seams as UV boundaries.
+ * This has the advantages of simplicity, and being valid/common to all UV maps.
+ * However, it means actual UV islands without matching UV seams will not be handled correctly.
+ * If a valid UV layer is passed as \a luvs parameter,
+ * UV coordinates are also used to detect islands boundaries.
+ *
+ * \note All this could be optimized.
+ * Not sure it would be worth the more complex code, though,
+ * those loops are supposed to be really quick to do.
+ */
 bool BKE_mesh_calc_islands_loop_poly_uvmap(struct MVert *verts,
                                            const int totvert,
                                            struct MEdge *edges,
@@ -235,6 +304,14 @@ bool BKE_mesh_calc_islands_loop_poly_uvmap(struct MVert *verts,
                                            const struct MLoopUV *luvs,
                                            MeshIslandStore *r_island_store);
 
+/**
+ * Calculate smooth groups from sharp edges.
+ *
+ * \param r_totgroup: The total number of groups, 1 or more.
+ * \return Polygon aligned array of group index values (bitflags if use_bitflags is true),
+ * starting at 1 (0 being used as 'invalid' flag).
+ * Note it's callers's responsibility to MEM_freeN returned array.
+ */
 int *BKE_mesh_calc_smoothgroups(const struct MEdge *medge,
                                 const int totedge,
                                 const struct MPoly *mpoly,