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

diff --git a/source/blender/blenkernel/BKE_anim_visualization.h b/source/blender/blenkernel/BKE_anim_visualization.h
index 4e86abeed8d..3b8c91b7fd2 100644
--- a/source/blender/blenkernel/BKE_anim_visualization.h
+++ b/source/blender/blenkernel/BKE_anim_visualization.h
@@ -38,13 +38,34 @@ struct bPoseChannel;
 /* ---------------------------------------------------- */
 /* Animation Visualization */
 
+/**
+ * Initialize the default settings for animation visualization.
+ */
 void animviz_settings_init(struct bAnimVizSettings *avs);
 
+/**
+ * Make a copy of motion-path data, so that viewing with copy on write works.
+ */
 struct bMotionPath *animviz_copy_motionpath(const struct bMotionPath *mpath_src);
 
+/**
+ * Free the given motion path's cache.
+ */
 void animviz_free_motionpath_cache(struct bMotionPath *mpath);
+/**
+ * Free the given motion path instance and its data.
+ * \note this frees the motion path given!
+ */
 void animviz_free_motionpath(struct bMotionPath *mpath);
 
+/**
+ * Setup motion paths for the given data.
+ * \note Only used when explicitly calculating paths on bones which may/may not be consider already
+ *
+ * \param scene: Current scene (for frame ranges, etc.)
+ * \param ob: Object to add paths for (must be provided)
+ * \param pchan: Posechannel to add paths for (optional; if not provided, object-paths are assumed)
+ */
 struct bMotionPath *animviz_verify_motionpaths(struct ReportList *reports,
                                                struct Scene *scene,
                                                struct Object *ob,