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, 13 insertions, 0 deletions

diff --git a/source/blender/blenkernel/BKE_mesh_remap.h b/source/blender/blenkernel/BKE_mesh_remap.h
index 7f8f028c26b..c33b3800aa4 100644
--- a/source/blender/blenkernel/BKE_mesh_remap.h
+++ b/source/blender/blenkernel/BKE_mesh_remap.h
@@ -161,11 +161,24 @@ void BKE_mesh_remap_calc_source_cddata_masks_from_map_modes(
     const int poly_mode,
     struct CustomData_MeshMasks *cddata_mask);
 
+/**
+ * Compute a value of the difference between both given meshes.
+ * The smaller the result, the better the match.
+ *
+ * We return the inverse of the average of the inversed
+ * shortest distance from each dst vertex to src ones.
+ * In other words, beyond a certain (relatively small) distance, all differences have more or less
+ * the same weight in final result, which allows to reduce influence of a few high differences,
+ * in favor of a global good matching.
+ */
 float BKE_mesh_remap_calc_difference_from_mesh(const struct SpaceTransform *space_transform,
                                                const struct MVert *verts_dst,
                                                const int numverts_dst,
                                                struct Mesh *me_src);
 
+/**
+ * Set r_space_transform so that best bbox of dst matches best bbox of src.
+ */
 void BKE_mesh_remap_find_best_match_from_mesh(const struct MVert *verts_dst,
                                               const int numverts_dst,
                                               struct Mesh *me_src,