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, 58 insertions, 5 deletions

diff --git a/source/blender/blenkernel/BKE_bvhutils.h b/source/blender/blenkernel/BKE_bvhutils.h
index bb95985ef4c..50fef9149ad 100644
--- a/source/blender/blenkernel/BKE_bvhutils.h
+++ b/source/blender/blenkernel/BKE_bvhutils.h
@@ -48,7 +48,7 @@ struct BVHCache;
 typedef struct BVHTreeFromEditMesh {
   struct BVHTree *tree;
 
-  /** Default callbacks to bvh nearest and ray-cast. */
+  /** Default callbacks to BVH nearest and ray-cast. */
   BVHTree_NearestPointCallback nearest_callback;
   BVHTree_RayCastCallback raycast_callback;
 
@@ -65,7 +65,7 @@ typedef struct BVHTreeFromEditMesh {
 typedef struct BVHTreeFromMesh {
   struct BVHTree *tree;
 
-  /** Default callbacks to bvh nearest and ray-cast. */
+  /** Default callbacks to BVH nearest and ray-cast. */
   BVHTree_NearestPointCallback nearest_callback;
   BVHTree_RayCastCallback raycast_callback;
 
@@ -105,7 +105,7 @@ typedef enum BVHCacheType {
 } BVHCacheType;
 
 /**
- * Builds a bvh tree where nodes are the relevant elements of the given mesh.
+ * Builds a BVH tree where nodes are the relevant elements of the given mesh.
  * Configures #BVHTreeFromMesh.
  *
  * The tree is build in mesh space coordinates, this means special care must be made on queries
@@ -113,11 +113,14 @@ typedef enum BVHCacheType {
  * Reason for this is that bvh_from_mesh_* can use a cache in some cases and so it
  * becomes possible to reuse a #BVHTree.
  *
- * free_bvhtree_from_mesh should be called when the tree is no longer needed.
+ * #free_bvhtree_from_mesh should be called when the tree is no longer needed.
  */
 BVHTree *bvhtree_from_editmesh_verts(
     BVHTreeFromEditMesh *data, struct BMEditMesh *em, float epsilon, int tree_type, int axis);
 
+/**
+ * Builds a BVH-tree where nodes are the vertices of the given `em`.
+ */
 BVHTree *bvhtree_from_editmesh_verts_ex(BVHTreeFromEditMesh *data,
                                         struct BMEditMesh *em,
                                         const BLI_bitmap *mask,
@@ -129,6 +132,13 @@ BVHTree *bvhtree_from_editmesh_verts_ex(BVHTreeFromEditMesh *data,
                                         struct BVHCache **bvh_cache_p,
                                         ThreadMutex *mesh_eval_mutex);
 
+/**
+ * Builds a BVH-tree where nodes are the given vertices (NOTE: does not copy given `vert`!).
+ * \param vert_allocated: if true, vert freeing will be done when freeing data.
+ * \param verts_mask: if not null, true elements give which vert to add to BVH-tree.
+ * \param verts_num_active: if >= 0, number of active verts to add to BVH-tree
+ * (else will be computed from mask).
+ */
 BVHTree *bvhtree_from_mesh_verts_ex(struct BVHTreeFromMesh *data,
                                     const struct MVert *vert,
                                     const int verts_num,
@@ -145,6 +155,9 @@ BVHTree *bvhtree_from_mesh_verts_ex(struct BVHTreeFromMesh *data,
 BVHTree *bvhtree_from_editmesh_edges(
     BVHTreeFromEditMesh *data, struct BMEditMesh *em, float epsilon, int tree_type, int axis);
 
+/**
+ * Builds a BVH-tree where nodes are the edges of the given `em`.
+ */
 BVHTree *bvhtree_from_editmesh_edges_ex(BVHTreeFromEditMesh *data,
                                         struct BMEditMesh *em,
                                         const BLI_bitmap *edges_mask,
@@ -156,6 +169,14 @@ BVHTree *bvhtree_from_editmesh_edges_ex(BVHTreeFromEditMesh *data,
                                         struct BVHCache **bvh_cache_p,
                                         ThreadMutex *mesh_eval_mutex);
 
+/**
+ * Builds a BVH-tree where nodes are the given edges.
+ * \param vert, vert_allocated: if true, elem freeing will be done when freeing data.
+ * \param edge, edge_allocated: if true, elem freeing will be done when freeing data.
+ * \param edges_mask: if not null, true elements give which vert to add to BVH-tree.
+ * \param edges_num_active: if >= 0, number of active edges to add to BVH-tree
+ * (else will be computed from mask).
+ */
 BVHTree *bvhtree_from_mesh_edges_ex(struct BVHTreeFromMesh *data,
                                     const struct MVert *vert,
                                     const bool vert_allocated,
@@ -171,6 +192,15 @@ BVHTree *bvhtree_from_mesh_edges_ex(struct BVHTreeFromMesh *data,
                                     struct BVHCache **bvh_cache_p,
                                     ThreadMutex *mesh_eval_mutex);
 
+/**
+ * Builds a BVH-tree where nodes are the given tessellated faces
+ * (NOTE: does not copy given mfaces!).
+ * \param vert_allocated: if true, vert freeing will be done when freeing data.
+ * \param face_allocated: if true, face freeing will be done when freeing data.
+ * \param faces_mask: if not null, true elements give which faces to add to BVH-tree.
+ * \param faces_num_active: if >= 0, number of active faces to add to BVH-tree
+ * (else will be computed from mask).
+ */
 BVHTree *bvhtree_from_mesh_faces_ex(struct BVHTreeFromMesh *data,
                                     const struct MVert *vert,
                                     const bool vert_allocated,
@@ -189,6 +219,9 @@ BVHTree *bvhtree_from_mesh_faces_ex(struct BVHTreeFromMesh *data,
 BVHTree *bvhtree_from_editmesh_looptri(
     BVHTreeFromEditMesh *data, struct BMEditMesh *em, float epsilon, int tree_type, int axis);
 
+/**
+ * Builds a BVH-tree where nodes are the `looptri` faces of the given `bm`.
+ */
 BVHTree *bvhtree_from_editmesh_looptri_ex(BVHTreeFromEditMesh *data,
                                           struct BMEditMesh *em,
                                           const BLI_bitmap *mask,
@@ -200,6 +233,11 @@ BVHTree *bvhtree_from_editmesh_looptri_ex(BVHTreeFromEditMesh *data,
                                           struct BVHCache **bvh_cache_p,
                                           ThreadMutex *mesh_eval_mutex);
 
+/**
+ * Builds a BVH-tree where nodes are the looptri faces of the given mesh.
+ *
+ * \note for edit-mesh this is currently a duplicate of #bvhtree_from_mesh_faces_ex
+ */
 BVHTree *bvhtree_from_mesh_looptri_ex(struct BVHTreeFromMesh *data,
                                       const struct MVert *vert,
                                       const bool vert_allocated,
@@ -217,11 +255,20 @@ BVHTree *bvhtree_from_mesh_looptri_ex(struct BVHTreeFromMesh *data,
                                       struct BVHCache **bvh_cache_p,
                                       ThreadMutex *mesh_eval_mutex);
 
+/**
+ * Builds or queries a BVH-cache for the cache BVH-tree of the request type.
+ *
+ * \note This function only fills a cache, and therefore the mesh argument can
+ * be considered logically const. Concurrent access is protected by a mutex.
+ */
 BVHTree *BKE_bvhtree_from_mesh_get(struct BVHTreeFromMesh *data,
                                    const struct Mesh *mesh,
                                    const BVHCacheType bvh_cache_type,
                                    const int tree_type);
 
+/**
+ * Builds or queries a BVH-cache for the cache BVH-tree of the request type.
+ */
 BVHTree *BKE_bvhtree_from_editmesh_get(BVHTreeFromEditMesh *data,
                                        struct BMEditMesh *em,
                                        const int tree_type,
@@ -230,9 +277,12 @@ BVHTree *BKE_bvhtree_from_editmesh_get(BVHTreeFromEditMesh *data,
                                        ThreadMutex *mesh_eval_mutex);
 
 /**
- * Frees data allocated by a call to bvhtree_from_mesh_*.
+ * Frees data allocated by a call to `bvhtree_from_editmesh_*`.
  */
 void free_bvhtree_from_editmesh(struct BVHTreeFromEditMesh *data);
+/**
+ * Frees data allocated by a call to `bvhtree_from_mesh_*`.
+ */
 void free_bvhtree_from_mesh(struct BVHTreeFromMesh *data);
 
 /**
@@ -272,6 +322,9 @@ void free_bvhtree_from_pointcloud(struct BVHTreeFromPointCloud *data);
 
 bool bvhcache_has_tree(const struct BVHCache *bvh_cache, const BVHTree *tree);
 struct BVHCache *bvhcache_init(void);
+/**
+ * Frees a BVH-cache.
+ */
 void bvhcache_free(struct BVHCache *bvh_cache);
 
 #ifdef __cplusplus