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, 32 insertions, 7 deletions

diff --git a/source/blender/blenkernel/BKE_softbody.h b/source/blender/blenkernel/BKE_softbody.h
index 58dc90f62dc..5d010fa2155 100644
--- a/source/blender/blenkernel/BKE_softbody.h
+++ b/source/blender/blenkernel/BKE_softbody.h
@@ -46,16 +46,24 @@ typedef struct BodyPoint {
   float springweight;
 } BodyPoint;
 
-/* allocates and initializes general main data */
+/**
+ * Allocates and initializes general main data.
+ */
 extern struct SoftBody *sbNew(void);
 
-/* frees internal data and soft-body itself */
+/**
+ * Frees internal data and soft-body itself.
+ */
 extern void sbFree(struct Object *ob);
 
-/* frees simulation data to reset simulation */
+/**
+ * Frees simulation data to reset simulation.
+ */
 extern void sbFreeSimulation(struct SoftBody *sb);
 
-/* do one simul step, reading and writing vertex locs from given array */
+/**
+ * Do one simulation step, reading and writing vertex locs from given array.
+ * */
 extern void sbObjectStep(struct Depsgraph *depsgraph,
                          struct Scene *scene,
                          struct Object *ob,
@@ -63,13 +71,30 @@ extern void sbObjectStep(struct Depsgraph *depsgraph,
                          float (*vertexCos)[3],
                          int numVerts);
 
-/* makes totally fresh start situation, resets time */
+/**
+ * Makes totally fresh start situation, resets time.
+ */
 extern void sbObjectToSoftbody(struct Object *ob);
 
-/* links the soft-body module to a 'test for Interrupt' function */
-/* pass NULL to unlink again */
+/**
+ * Soft-body global visible functions.
+ * Links the soft-body module to a 'test for Interrupt' function, pass NULL to clear the callback.
+ */
 extern void sbSetInterruptCallBack(int (*f)(void));
 
+/**
+ * A precise position vector denoting the motion of the center of mass give a rotation/scale matrix
+ * using averaging method, that's why estimate and not calculate see: this is kind of reverse
+ * engineering: having to states of a point cloud and recover what happened our advantage here we
+ * know the identity of the vertex there are others methods giving other results.
+ *
+ * \param ob: Any object that can do soft-body e.g. mesh, lattice, curve.
+ * \param lloc: Output of the calculated location (or NULL).
+ * \param lrot: Output of the calculated rotation (or NULL).
+ * \param lscale: Output for the calculated scale (or NULL).
+ *
+ * For velocity & 2nd order stuff see: #vcloud_estimate_transform_v3.
+ */
 extern void SB_estimate_transform(Object *ob, float lloc[3], float lrot[3][3], float lscale[3][3]);
 
 #ifdef __cplusplus