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, 5 insertions, 88 deletions

diff --git a/source/blender/blenkernel/intern/appdir.c b/source/blender/blenkernel/intern/appdir.c
index d872dc67dcb..a819459f989 100644
--- a/source/blender/blenkernel/intern/appdir.c
+++ b/source/blender/blenkernel/intern/appdir.c
@@ -99,15 +99,6 @@ static bool is_appdir_init = false;
 #  define ASSERT_IS_INIT() ((void)0)
 #endif
 
-/**
- * Sanity check to ensure correct API use in debug mode.
- *
- * Run this once the first level of arguments has been passed so we can be sure
- * `--env-system-datafiles`, and other `--env-*` arguments has been passed.
- *
- * Without this any callers to this module that run early on,
- * will miss out on changes from parsing arguments.
- */
 void BKE_appdir_init(void)
 {
 #ifndef NDEBUG
@@ -147,14 +138,6 @@ static char *blender_version_decimal(const int version)
 /** \name Default Directories
  * \{ */
 
-/**
- * Get the folder that's the "natural" starting point for browsing files on an OS.
- * - Unix: `$HOME`
- * - Windows: `%userprofile%/Documents`
- *
- * \note On Windows `Users/{MyUserName}/Documents` is used as it's the default location to save
- * documents.
- */
 const char *BKE_appdir_folder_default(void)
 {
 #ifndef WIN32
@@ -190,11 +173,6 @@ const char *BKE_appdir_folder_default_or_root(void)
   return path;
 }
 
-/**
- * Get the user's home directory, i.e.
- * - Unix: `$HOME`
- * - Windows: `%userprofile%`
- */
 const char *BKE_appdir_folder_home(void)
 {
 #ifndef WIN32
@@ -204,15 +182,6 @@ const char *BKE_appdir_folder_home(void)
 #endif
 }
 
-/**
- * Get the user's document directory, i.e.
- * - Linux: `$HOME/Documents`
- * - Windows: `%userprofile%/Documents`
- *
- * If this can't be found using OS queries (via Ghost), try manually finding it.
- *
- * \returns True if the path is valid and points to an existing directory.
- */
 bool BKE_appdir_folder_documents(char *dir)
 {
   dir[0] = '\0';
@@ -243,15 +212,6 @@ bool BKE_appdir_folder_documents(char *dir)
   return true;
 }
 
-/**
- * Get the user's cache directory, i.e.
- * - Linux: `$HOME/.cache/blender/`
- * - Windows: `%USERPROFILE%\AppData\Local\Blender Foundation\Blender\`
- * - MacOS: `/Library/Caches/Blender`
- *
- * \returns True if the path is valid. It doesn't create or checks format
- * if the `blender` folder exists. It does check if the parent of the path exists.
- */
 bool BKE_appdir_folder_caches(char *r_path, const size_t path_len)
 {
   r_path[0] = '\0';
@@ -276,9 +236,6 @@ bool BKE_appdir_folder_caches(char *r_path, const size_t path_len)
   return true;
 }
 
-/**
- * Gets a good default directory for fonts.
- */
 bool BKE_appdir_font_folder_default(char *dir)
 {
   char test_dir[FILE_MAXDIR];
@@ -458,10 +415,6 @@ static bool get_path_local(char *targetpath,
       targetpath, targetpath_len, folder_name, subfolder_name, version, check_is_dir);
 }
 
-/**
- * Check if this is an install with user files kept together
- * with the Blender executable and its installation files.
- */
 bool BKE_appdir_app_is_portable_install(void)
 {
   /* Detect portable install by the existence of `config` folder. */
@@ -626,13 +579,6 @@ static bool get_path_system(char *targetpath,
 /** \name Path Presets API
  * \{ */
 
-/**
- * Get a folder out of the \a folder_id presets for paths.
- *
- * \param subfolder: The name of a directory to check for,
- * this may contain path separators but must resolve to a directory, checked with #BLI_is_dir.
- * \return The path if found, NULL string if not.
- */
 bool BKE_appdir_folder_id_ex(const int folder_id,
                              const char *subfolder,
                              char *path,
@@ -746,9 +692,6 @@ const char *BKE_appdir_folder_id(const int folder_id, const char *subfolder)
   return NULL;
 }
 
-/**
- * Returns the path to a folder in the user area without checking that it actually exists first.
- */
 const char *BKE_appdir_folder_id_user_notest(const int folder_id, const char *subfolder)
 {
   const int version = BLENDER_VERSION;
@@ -795,9 +738,6 @@ const char *BKE_appdir_folder_id_user_notest(const int folder_id, const char *su
   return path;
 }
 
-/**
- * Returns the path to a folder in the user area, creating it if it doesn't exist.
- */
 const char *BKE_appdir_folder_id_create(const int folder_id, const char *subfolder)
 {
   const char *path;
@@ -823,10 +763,6 @@ const char *BKE_appdir_folder_id_create(const int folder_id, const char *subfold
   return path;
 }
 
-/**
- * Returns the path of the top-level version-specific local, user or system directory.
- * If check_is_dir, then the result will be NULL if the directory doesn't exist.
- */
 const char *BKE_appdir_folder_id_version(const int folder_id,
                                          const int version,
                                          const bool check_is_dir)
@@ -942,18 +878,12 @@ void BKE_appdir_program_path_init(const char *argv0)
   BLI_split_dir_part(g_app.program_filename, g_app.program_dirname, sizeof(g_app.program_dirname));
 }
 
-/**
- * Path to executable
- */
 const char *BKE_appdir_program_path(void)
 {
   BLI_assert(g_app.program_filename[0]);
   return g_app.program_filename;
 }
 
-/**
- * Path to directory of executable
- */
 const char *BKE_appdir_program_dir(void)
 {
   BLI_assert(g_app.program_dirname[0]);
@@ -1047,9 +977,6 @@ static const int app_template_directory_id[2] = {
     BLENDER_SYSTEM_SCRIPTS,
 };
 
-/**
- * Return true if templates exist
- */
 bool BKE_appdir_app_template_any(void)
 {
   char temp_dir[FILE_MAX];
@@ -1217,14 +1144,13 @@ static void tempdir_session_create(char *tempdir_session,
   BLI_strncpy(tempdir_session, tempdir, tempdir_session_len);
 }
 
-/**
- * Sets #g_app.temp_dirname_base to \a userdir if specified and is a valid directory,
- * otherwise chooses a suitable OS-specific temporary directory.
- * Sets #g_app.temp_dirname_session to a #mkdtemp
- * generated sub-dir of #g_app.temp_dirname_base.
- */
 void BKE_tempdir_init(const char *userdir)
 {
+  /* Sets #g_app.temp_dirname_base to \a userdir if specified and is a valid directory,
+   * otherwise chooses a suitable OS-specific temporary directory.
+   * Sets #g_app.temp_dirname_session to a #mkdtemp
+   * generated sub-dir of #g_app.temp_dirname_base. */
+
   where_is_temp(g_app.temp_dirname_base, sizeof(g_app.temp_dirname_base), userdir);
 
   /* Clear existing temp dir, if needed. */
@@ -1234,25 +1160,16 @@ void BKE_tempdir_init(const char *userdir)
       g_app.temp_dirname_session, sizeof(g_app.temp_dirname_session), g_app.temp_dirname_base);
 }
 
-/**
- * Path to temporary directory (with trailing slash)
- */
 const char *BKE_tempdir_session(void)
 {
   return g_app.temp_dirname_session[0] ? g_app.temp_dirname_session : BKE_tempdir_base();
 }
 
-/**
- * Path to persistent temporary directory (with trailing slash)
- */
 const char *BKE_tempdir_base(void)
 {
   return g_app.temp_dirname_base;
 }
 
-/**
- * Delete content of this instance's temp dir.
- */
 void BKE_tempdir_session_purge(void)
 {
   if (g_app.temp_dirname_session[0] && BLI_is_dir(g_app.temp_dirname_session)) {