Cleanup: move public doc-strings into headers for 'blenlib'

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

diff --git a/source/blender/blenlib/BLI_timecode.h b/source/blender/blenlib/BLI_timecode.h
index 5dfd9089598..768b9a896b0 100644
--- a/source/blender/blenlib/BLI_timecode.h
+++ b/source/blender/blenlib/BLI_timecode.h
@@ -29,6 +29,18 @@
 extern "C" {
 #endif
 
+/**
+ * Generate time-code/frame number string and store in \a str
+ *
+ * \param str: destination string
+ * \param maxncpy: maximum number of characters to copy `sizeof(str)`
+ * \param brevity_level: special setting for #View2D grid drawing,
+ *        used to specify how detailed we need to be
+ * \param time_seconds: time total time in seconds
+ * \param fps: frames per second, typically from the #FPS macro
+ * \param timecode_style: enum from #eTimecodeStyles
+ * \return length of \a str
+ */
 size_t BLI_timecode_string_from_time(char *str,
                                      const size_t maxncpy,
                                      const int brevity_level,
@@ -36,10 +48,30 @@ size_t BLI_timecode_string_from_time(char *str,
                                      const double scene_fps,
                                      const short timecode_style) ATTR_NONNULL();
 
+/**
+ * Generate time string and store in \a str
+ *
+ * \param str: destination string
+ * \param maxncpy: maximum number of characters to copy `sizeof(str)`
+ * \param time_seconds: time total time in seconds
+ * \return length of \a str
+ */
 size_t BLI_timecode_string_from_time_simple(char *str,
                                             const size_t maxncpy,
                                             const double time_seconds) ATTR_NONNULL();
 
+/**
+ * Generate time string and store in \a str
+ *
+ * \param str: destination string
+ * \param maxncpy: maximum number of characters to copy `sizeof(str)`
+ * \param brevity_level: special setting for #View2D grid drawing,
+ *        used to specify how detailed we need to be
+ * \param time_seconds: time total time in seconds
+ * \return length of \a str
+ *
+ * \note in some cases this is used to print non-seconds values.
+ */
 size_t BLI_timecode_string_from_time_seconds(char *str,
                                              const size_t maxncpy,
                                              const int brevity_level,