diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/BKE_appdir.h | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
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
Diffstat (limited to 'source/blender/blenkernel/BKE_appdir.h')
-rw-r--r-- | source/blender/blenkernel/BKE_appdir.h | 100 |
1 files changed, 94 insertions, 6 deletions
diff --git a/source/blender/blenkernel/BKE_appdir.h b/source/blender/blenkernel/BKE_appdir.h index 65485058dd7..dd589282bdd 100644 --- a/source/blender/blenkernel/BKE_appdir.h +++ b/source/blender/blenkernel/BKE_appdir.h @@ -17,6 +17,9 @@ /** \file * \ingroup bke + * + * \note on naming: typical _get() suffix is omitted here, + * since its the main purpose of the API. */ #include <stddef.h> @@ -29,54 +32,139 @@ extern "C" { struct ListBase; +/** + * 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); void BKE_appdir_exit(void); -/* note on naming: typical _get() suffix is omitted here, - * since its the main purpose of the API. */ +/** + * 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) ATTR_WARN_UNUSED_RESULT; const char *BKE_appdir_folder_root(void) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL; const char *BKE_appdir_folder_default_or_root(void) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL; +/** + * Get the user's home directory, i.e. + * - Unix: `$HOME` + * - Windows: `%userprofile%` + */ const char *BKE_appdir_folder_home(void); +/** + * 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); +/** + * 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, size_t path_len); +/** + * 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, size_t path_len); const char *BKE_appdir_folder_id(const int folder_id, const char *subfolder); +/** + * 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); +/** + * 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); +/** + * 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); +/** + * 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); +/** + * Return true if templates exist + */ bool BKE_appdir_app_template_any(void); bool BKE_appdir_app_template_id_search(const char *app_template, char *path, size_t path_len); bool BKE_appdir_app_template_has_userpref(const char *app_template); void BKE_appdir_app_templates(struct ListBase *templates); -/* Initialize path to program executable */ +/** + * Initialize path to program executable. + */ void BKE_appdir_program_path_init(const char *argv0); +/** + * Path to executable + */ const char *BKE_appdir_program_path(void); +/** + * Path to directory of executable + */ const char *BKE_appdir_program_dir(void); -/* Return OS fonts directory. */ +/** + * Gets a good default directory for fonts. + */ bool BKE_appdir_font_folder_default(char *dir); -/* find python executable */ +/** + * Find Python executable. + */ bool BKE_appdir_program_python_search(char *fullpath, const size_t fullpath_len, const int version_major, const int version_minor); -/* Initialize path to temporary directory. */ +/** + * Initialize path to temporary directory. + */ void BKE_tempdir_init(const char *userdir); +/** + * Path to persistent temporary directory (with trailing slash) + */ const char *BKE_tempdir_base(void); +/** + * Path to temporary directory (with trailing slash) + */ const char *BKE_tempdir_session(void); +/** + * Delete content of this instance's temp dir. + */ void BKE_tempdir_session_purge(void); /* folder_id */ |