Cleanup: rename BKE_appdir_folder_id_version, improve doc-strings

Rename BKE_appdir_folder_id_version to
BKE_appdir_resource_path_id_with_version because BKE_appdir_folder_id
and BKE_appdir_folder_id_version didn't accept compatible arguments.

Also add notes to GHOST_getSystemDir & GHOST_getUserDir that
BKE_appdir_resource_path_id(..) should be used instead (in most cases).

1 files changed, 7 insertions, 1 deletions

diff --git a/intern/ghost/GHOST_Path-api.h b/intern/ghost/GHOST_Path-api.h
index d303654d3e6..42c7cc75668 100644
--- a/intern/ghost/GHOST_Path-api.h
+++ b/intern/ghost/GHOST_Path-api.h
@@ -30,13 +30,19 @@ extern GHOST_TSuccess GHOST_DisposeSystemPaths(void);
 /**
  * Determine the base dir in which shared resources are located. It will first try to use
  * "unpack and run" path, then look for properly installed path, including versioning.
- * \return Unsigned char string pointing to system dir (eg /usr/share/blender/).
+ * \return Unsigned char string pointing to system dir (eg `/usr/share/blender/`).
+ *
+ * \note typically: `BKE_appdir_resource_path_id(BLENDER_RESOURCE_PATH_SYSTEM, false)` should be
+ * used instead of this function directly as it ensures environment variable overrides are used.
  */
 extern const char *GHOST_getSystemDir(int version, const char *versionstr);
 
 /**
  * Determine the base dir in which user configuration is stored, including versioning.
  * \return Unsigned char string pointing to user dir (eg ~).
+ *
+ * \note typically: `BKE_appdir_resource_path_id(BLENDER_RESOURCE_PATH_USER, false)` should be
+ * used instead of this function directly as it ensures environment variable overrides are used.
  */
 extern const char *GHOST_getUserDir(int version, const char *versionstr);