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, 14 insertions, 24 deletions

diff --git a/source/blender/blenkernel/intern/particle.c b/source/blender/blenkernel/intern/particle.c
index b868ee57289..18b3d69d59f 100644
--- a/source/blender/blenkernel/intern/particle.c
+++ b/source/blender/blenkernel/intern/particle.c
@@ -556,7 +556,6 @@ static void get_cpa_texture(Mesh *mesh,
                             int event,
                             float cfra);
 
-/* few helpers for countall etc. */
 int count_particles(ParticleSystem *psys)
 {
   ParticleSettings *part = psys->part;
@@ -646,7 +645,7 @@ static void psys_free_path_cache_buffers(ParticleCacheKey **cache, ListBase *buf
 /************************************************/
 /*          Getting stuff                       */
 /************************************************/
-/* get object's active particle system safely */
+
 ParticleSystem *psys_get_current(Object *ob)
 {
   ParticleSystem *psys;
@@ -914,9 +913,11 @@ int psys_uses_gravity(ParticleSimulationData *sim)
   return sim->scene->physics_settings.flag & PHYS_GLOBAL_GRAVITY && sim->psys->part &&
          sim->psys->part->effector_weights->global_gravity != 0.0f;
 }
+
 /************************************************/
 /*          Freeing stuff                       */
 /************************************************/
+
 static void fluid_free_settings(SPHFluidSettings *fluid)
 {
   if (fluid) {
@@ -1056,7 +1057,6 @@ void psys_free_pdd(ParticleSystem *psys)
     psys->pdd->partsize = 0;
   }
 }
-/* free everything */
 void psys_free(Object *ob, ParticleSystem *psys)
 {
   if (psys) {
@@ -1204,6 +1204,7 @@ void psys_copy_particles(ParticleSystem *psys_dst, ParticleSystem *psys_src)
 /************************************************/
 /*          Interpolation                       */
 /************************************************/
+
 static float interpolate_particle_value(
     float v1, float v2, float v3, float v4, const float w[4], int four)
 {
@@ -1671,7 +1672,7 @@ static void interpolate_pathcache(ParticleCacheKey *first, float t, ParticleCach
 /************************************************/
 /*          Particles on a dm                   */
 /************************************************/
-/* interpolate a location on a face based on face coordinates */
+
 void psys_interpolate_face(MVert *mvert,
                            MFace *mface,
                            MTFace *tface,
@@ -1903,18 +1904,6 @@ static void psys_origspace_to_w(OrigSpaceFace *osface, int quad, const float w[4
   }
 }
 
-/**
- * Find the final derived mesh tessface for a particle, from its original tessface index.
- * This is slow and can be optimized but only for many lookups.
- *
- * \param mesh_final: Final mesh, it may not have the same topology as original mesh.
- * \param mesh_original: Original mesh, use for accessing #MPoly to #MFace mapping.
- * \param findex_orig: The input tessface index.
- * \param fw: Face weights (position of the particle inside the \a findex_orig tessface).
- * \param poly_nodes: May be NULL, otherwise an array of linked list,
- * one for each final \a mesh_final polygon, containing all its tessfaces indices.
- * \return The \a mesh_final tessface index.
- */
 int psys_particle_dm_face_lookup(Mesh *mesh_final,
                                  Mesh *mesh_original,
                                  int findex_orig,
@@ -2096,7 +2085,6 @@ static int psys_map_index_on_dm(Mesh *mesh,
   return 1;
 }
 
-/* interprets particle data to get a point on a mesh in object space */
 void psys_particle_on_dm(Mesh *mesh_final,
                          int from,
                          int index,
@@ -2218,9 +2206,11 @@ ParticleSystemModifierData *psys_get_modifier(Object *ob, ParticleSystem *psys)
   }
   return NULL;
 }
+
 /************************************************/
 /*          Particles on a shape                */
 /************************************************/
+
 /* ready for future use */
 static void psys_particle_on_shape(int UNUSED(distr),
                                    int UNUSED(index),
@@ -2249,6 +2239,7 @@ static void psys_particle_on_shape(int UNUSED(distr),
     copy_v3_v3(orco, zerovec);
   }
 }
+
 /************************************************/
 /*          Particles on emitter                */
 /************************************************/
@@ -2323,6 +2314,7 @@ void psys_particle_on_emitter(ParticleSystemModifierData *psmd,
     psys_particle_on_shape(from, index, fuv, vec, nor, utan, vtan, orco);
   }
 }
+
 /************************************************/
 /*          Path Cache                          */
 /************************************************/
@@ -3275,11 +3267,6 @@ static void cache_key_incremental_rotation(ParticleCacheKey *key0,
   }
 }
 
-/**
- * Calculates paths ready for drawing/rendering
- * - Useful for making use of opengl vertex arrays for super fast strand drawing.
- * - Makes child strands possible and creates them too into the cache.
- * - Cached path data is also used to determine cut position for the editmode tool. */
 void psys_cache_paths(ParticleSimulationData *sim, float cfra, const bool use_render_params)
 {
   PARTICLE_PSMD;
@@ -3762,9 +3749,11 @@ void psys_cache_edit_paths(Depsgraph *depsgraph,
     }
   }
 }
+
 /************************************************/
 /*          Particle Key handling               */
 /************************************************/
+
 void copy_particle_key(ParticleKey *to, ParticleKey *from, int time)
 {
   if (time) {
@@ -3924,6 +3913,7 @@ void psys_mat_hair_to_global(
 /************************************************/
 /*          ParticleSettings handling           */
 /************************************************/
+
 static ModifierData *object_add_or_copy_particle_system(
     Main *bmain, Scene *scene, Object *ob, const char *name, const ParticleSystem *psys_orig)
 {
@@ -4460,9 +4450,11 @@ void psys_get_texture(
   CLAMP_WARP_PARTICLE_TEXTURE_POS(PAMAP_DAMP, ptex->damp);
   CLAMP_PARTICLE_TEXTURE_POS(PAMAP_LENGTH, ptex->length);
 }
+
 /************************************************/
 /*          Particle State                      */
 /************************************************/
+
 float psys_get_timestep(ParticleSimulationData *sim)
 {
   return 0.04f * sim->psys->part->timetweak;
@@ -4588,7 +4580,6 @@ static void get_child_modifier_parameters(ParticleSettings *part,
         ctx->mesh, cpa_from, cpa_num, cpa_fuv, ctx->vg_twist);
   }
 }
-/* gets hair (or keyed) particles state at the "path time" specified in state->time */
 void psys_get_particle_on_path(ParticleSimulationData *sim,
                                int p,
                                ParticleKey *state,
@@ -4857,7 +4848,6 @@ void psys_get_particle_on_path(ParticleSimulationData *sim,
     }
   }
 }
-/* gets particle's state at a time, returns 1 if particle exists and can be seen and 0 if not */
 int psys_get_particle_state(ParticleSimulationData *sim, int p, ParticleKey *state, int always)
 {
   ParticleSystem *psys = sim->psys;