Cleanup: move public doc-strings into headers for various API's

Some doc-strings were skipped because of blank-lines between
the doc-string and the symbol and needed to be moved manually.

- 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.

Ref T92709

5 files changed, 77 insertions, 37 deletions

diff --git a/source/blender/blenkernel/BKE_camera.h b/source/blender/blenkernel/BKE_camera.h
index d91b6505672..45bfef82302 100644
--- a/source/blender/blenkernel/BKE_camera.h
+++ b/source/blender/blenkernel/BKE_camera.h
@@ -123,6 +123,8 @@ void BKE_camera_view_frame(const struct Scene *scene,
 
 /**
  * \param r_scale: only valid/useful for orthographic cameras.
+ *
+ * \note Don't move the camera, just yield the fit location.
  */
 bool BKE_camera_view_frame_fit_to_scene(struct Depsgraph *depsgraph,
                                         const struct Scene *scene,
diff --git a/source/blender/blenkernel/BKE_rigidbody.h b/source/blender/blenkernel/BKE_rigidbody.h
index 6b6bed29245..1c9bad7fbe8 100644
--- a/source/blender/blenkernel/BKE_rigidbody.h
+++ b/source/blender/blenkernel/BKE_rigidbody.h
@@ -38,8 +38,9 @@ struct Object;
 struct ReportList;
 struct Scene;
 
-/* -------------- */
-/* Memory Management */
+/* -------------------------------------------------------------------- */
+/** \name Memory Management
+ * \{ */
 
 /**
  * Free rigid-body world.
@@ -61,6 +62,12 @@ void BKE_rigidbody_object_copy(struct Main *bmain,
                                const struct Object *ob_src,
                                const int flag);
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Iterator
+ * \{ */
+
 /**
  * Callback format for performing operations on ID-pointers for rigid-body world.
  */
@@ -73,16 +80,27 @@ void BKE_rigidbody_world_id_loop(struct RigidBodyWorld *rbw,
                                  RigidbodyWorldIDFunc func,
                                  void *userdata);
 
-/* -------------- */
-/* Setup */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Setup
+ * \{ */
 
 /**
+ * Set up RigidBody world.
+ *
  * Create Blender-side settings data - physics objects not initialized yet.
  */
 struct RigidBodyWorld *BKE_rigidbody_create_world(struct Scene *scene);
+/**
+ * Add rigid body settings to the specified object.
+ */
 struct RigidBodyOb *BKE_rigidbody_create_object(struct Scene *scene,
                                                 struct Object *ob,
                                                 short type);
+/**
+ * Add rigid body constraint to the specified object.
+ */
 struct RigidBodyCon *BKE_rigidbody_create_constraint(struct Scene *scene,
                                                      struct Object *ob,
                                                      short type);
@@ -110,16 +128,35 @@ void BKE_rigidbody_world_groups_relink(struct RigidBodyWorld *rbw);
 /**
  * 'validate' (i.e. make new or replace old) Physics-Engine objects.
  */
+/**
+ * Create physics sim world given RigidBody world settings
+ *
+ * \note this does NOT update object references that the scene uses,
+ * in case those aren't ready yet!
+ */
 void BKE_rigidbody_validate_sim_world(struct Scene *scene,
                                       struct RigidBodyWorld *rbw,
                                       bool rebuild);
 
+/**
+ * Helper function to calculate volume of rigid-body object.
+
+ * TODO: allow a parameter to specify method used to calculate this?
+ */
 void BKE_rigidbody_calc_volume(struct Object *ob, float *r_vol);
 void BKE_rigidbody_calc_center_of_mass(struct Object *ob, float r_center[3]);
 
-/* -------------- */
-/* Utilities */
+/** \} */
 
+/* -------------------------------------------------------------------- */
+/** \name Utilities
+ * \{ */
+
+/**
+ * Get RigidBody world for the given scene, creating one if needed
+ *
+ * \param scene: Scene to find active Rigid Body world for.
+ */
 struct RigidBodyWorld *BKE_rigidbody_get_world(struct Scene *scene);
 bool BKE_rigidbody_add_object(struct Main *bmain,
                               struct Scene *scene,
@@ -136,8 +173,11 @@ void BKE_rigidbody_remove_constraint(struct Main *bmain,
                                      struct Object *ob,
                                      const bool free_us);
 
-/* -------------- */
-/* Utility Macros */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Utility Macros
+ * \{ */
 
 /**
  * Get mass of Rigid Body Object to supply to RigidBody simulators.
@@ -157,24 +197,44 @@ void BKE_rigidbody_remove_constraint(struct Main *bmain,
        ((rbo)->margin) : \
        (0.04f))
 
-/* -------------- */
-/* Simulation */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Simulation
+ * \{ */
 
+/**
+ * Used when canceling transforms - return rigidbody and object to initial states.
+ */
 void BKE_rigidbody_aftertrans_update(struct Object *ob,
                                      float loc[3],
                                      float rot[3],
                                      float quat[4],
                                      float rotAxis[3],
                                      float rotAngle);
+/**
+ * Sync rigid body and object transformations.
+ */
 void BKE_rigidbody_sync_transforms(struct RigidBodyWorld *rbw, struct Object *ob, float ctime);
 bool BKE_rigidbody_check_sim_running(struct RigidBodyWorld *rbw, float ctime);
 bool BKE_rigidbody_is_affected_by_simulation(struct Object *ob);
 void BKE_rigidbody_cache_reset(struct RigidBodyWorld *rbw);
+/**
+ * Rebuild rigid body world.
+ *
+ * NOTE: this needs to be called before frame update to work correctly.
+ */
 void BKE_rigidbody_rebuild_world(struct Depsgraph *depsgraph, struct Scene *scene, float ctime);
+/**
+ * Run RigidBody simulation for the specified physics world.
+ */
 void BKE_rigidbody_do_simulation(struct Depsgraph *depsgraph, struct Scene *scene, float ctime);
 
-/* -------------------- */
-/* Depsgraph evaluation */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Depsgraph evaluation
+ * \{ */
 
 void BKE_rigidbody_rebuild_sim(struct Depsgraph *depsgraph, struct Scene *scene);
 
@@ -184,6 +244,8 @@ void BKE_rigidbody_object_sync_transforms(struct Depsgraph *depsgraph,
                                           struct Scene *scene,
                                           struct Object *ob);
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/blenkernel/intern/camera.c b/source/blender/blenkernel/intern/camera.c
index 8fa787b2222..7940936b64a 100644
--- a/source/blender/blenkernel/intern/camera.c
+++ b/source/blender/blenkernel/intern/camera.c
@@ -756,7 +756,6 @@ static bool camera_frame_fit_calc_from_data(CameraParams *params,
   return false;
 }
 
-/* don't move the camera, just yield the fit location */
 bool BKE_camera_view_frame_fit_to_scene(
     Depsgraph *depsgraph, const Scene *scene, Object *camera_ob, float r_co[3], float *r_scale)
 {
diff --git a/source/blender/blenkernel/intern/mesh_mapping.c b/source/blender/blenkernel/intern/mesh_mapping.c
index f35a44e8b34..415cce95d38 100644
--- a/source/blender/blenkernel/intern/mesh_mapping.c
+++ b/source/blender/blenkernel/intern/mesh_mapping.c
@@ -42,9 +42,6 @@
  * \{ */
 
 /* ngon version wip, based on BM_uv_vert_map_create */
-/* this replaces the non bmesh function (in trunk) which takes MTFace's,
- * if we ever need it back we could but for now this replaces it because its unused. */
-
 UvVertMap *BKE_mesh_uv_vert_map_create(const MPoly *mpoly,
                                        const MLoop *mloop,
                                        const MLoopUV *mloopuv,
diff --git a/source/blender/blenkernel/intern/rigidbody.c b/source/blender/blenkernel/intern/rigidbody.c
index 5bbe8ce2701..75e9bc2fbee 100644
--- a/source/blender/blenkernel/intern/rigidbody.c
+++ b/source/blender/blenkernel/intern/rigidbody.c
@@ -634,8 +634,6 @@ static void rigidbody_validate_sim_shape(RigidBodyWorld *rbw, Object *ob, bool r
 
 /* --------------------- */
 
-/* helper function to calculate volume of rigidbody object */
-/* TODO: allow a parameter to specify method used to calculate this? */
 void BKE_rigidbody_calc_volume(Object *ob, float *r_vol)
 {
   RigidBodyOb *rbo = ob->rigidbody_object;
@@ -1130,12 +1128,6 @@ static void rigidbody_validate_sim_constraint(RigidBodyWorld *rbw, Object *ob, b
 
 /* --------------------- */
 
-/**
- * Create physics sim world given RigidBody world settings
- *
- * \note this does NOT update object references that the scene uses,
- * in case those aren't ready yet!
- */
 void BKE_rigidbody_validate_sim_world(Scene *scene, RigidBodyWorld *rbw, bool rebuild)
 {
   /* sanity checks */
@@ -1158,7 +1150,6 @@ void BKE_rigidbody_validate_sim_world(Scene *scene, RigidBodyWorld *rbw, bool re
 /* ************************************** */
 /* Setup Utilities - Create Settings Blocks */
 
-/* Set up RigidBody world */
 RigidBodyWorld *BKE_rigidbody_create_world(Scene *scene)
 {
   /* try to get whatever RigidBody world that might be representing this already */
@@ -1243,7 +1234,6 @@ void BKE_rigidbody_world_id_loop(RigidBodyWorld *rbw, RigidbodyWorldIDFunc func,
   }
 }
 
-/* Add rigid body settings to the specified object */
 RigidBodyOb *BKE_rigidbody_create_object(Scene *scene, Object *ob, short type)
 {
   RigidBodyOb *rbo;
@@ -1306,7 +1296,6 @@ RigidBodyOb *BKE_rigidbody_create_object(Scene *scene, Object *ob, short type)
   return rbo;
 }
 
-/* Add rigid body constraint to the specified object */
 RigidBodyCon *BKE_rigidbody_create_constraint(Scene *scene, Object *ob, short type)
 {
   RigidBodyCon *rbc;
@@ -1426,11 +1415,6 @@ void BKE_rigidbody_main_collection_object_add(Main *bmain, Collection *collectio
 /* ************************************** */
 /* Utilities API */
 
-/**
- * Get RigidBody world for the given scene, creating one if needed
- *
- * \param scene: Scene to find active Rigid Body world for.
- */
 RigidBodyWorld *BKE_rigidbody_get_world(Scene *scene)
 {
   /* sanity check */
@@ -2055,7 +2039,6 @@ bool BKE_rigidbody_check_sim_running(RigidBodyWorld *rbw, float ctime)
   return (rbw && (rbw->flag & RBW_FLAG_MUTED) == 0 && ctime > rbw->shared->pointcache->startframe);
 }
 
-/* Sync rigid body and object transformations */
 void BKE_rigidbody_sync_transforms(RigidBodyWorld *rbw, Object *ob, float ctime)
 {
   if (!BKE_rigidbody_is_affected_by_simulation(ob)) {
@@ -2086,7 +2069,6 @@ void BKE_rigidbody_sync_transforms(RigidBodyWorld *rbw, Object *ob, float ctime)
   }
 }
 
-/* Used when canceling transforms - return rigidbody and object to initial states */
 void BKE_rigidbody_aftertrans_update(
     Object *ob, float loc[3], float rot[3], float quat[4], float rotAxis[3], float rotAngle)
 {
@@ -2165,8 +2147,6 @@ void BKE_rigidbody_cache_reset(RigidBodyWorld *rbw)
 
 /* ------------------ */
 
-/* Rebuild rigid body world */
-/* NOTE: this needs to be called before frame update to work correctly */
 void BKE_rigidbody_rebuild_world(Depsgraph *depsgraph, Scene *scene, float ctime)
 {
   RigidBodyWorld *rbw = scene->rigidbody_world;
@@ -2206,7 +2186,6 @@ void BKE_rigidbody_rebuild_world(Depsgraph *depsgraph, Scene *scene, float ctime
   }
 }
 
-/* Run RigidBody simulation for the specified physics world */
 void BKE_rigidbody_do_simulation(Depsgraph *depsgraph, Scene *scene, float ctime)
 {
   RigidBodyWorld *rbw = scene->rigidbody_world;
@@ -2304,6 +2283,7 @@ void BKE_rigidbody_object_copy(Main *bmain, Object *ob_dst, const Object *ob_src
 void BKE_rigidbody_validate_sim_world(Scene *scene, RigidBodyWorld *rbw, bool rebuild)
 {
 }
+
 void BKE_rigidbody_calc_volume(Object *ob, float *r_vol)
 {
   if (r_vol) {