From f29e9e0d3c9b7c68b303579d84c1416044e5e876 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sat, 3 Oct 2020 20:51:47 +1000 Subject: Cleanup: comments for appdir Use doxy syntax & minor improvements. --- source/blender/blenkernel/intern/appdir.c | 131 ++++++++++++++++-------------- 1 file changed, 71 insertions(+), 60 deletions(-) (limited to 'source') diff --git a/source/blender/blenkernel/intern/appdir.c b/source/blender/blenkernel/intern/appdir.c index e5bcc2e836b..543e0091131 100644 --- a/source/blender/blenkernel/intern/appdir.c +++ b/source/blender/blenkernel/intern/appdir.c @@ -62,14 +62,21 @@ /* local */ static CLG_LogRef LOG = {"bke.appdir"}; -static char bprogname[FILE_MAX]; /* full path to program executable */ -static char bprogdir[FILE_MAX]; /* full path to directory in which executable is located */ -static char btempdir_base[FILE_MAX]; /* persistent temporary directory */ -static char btempdir_session[FILE_MAX] = ""; /* volatile temporary directory */ - -/* This is now only used to really get the user's default document folder */ -/* On Windows I chose the 'Users//Documents' since it's used - * as default location to save documents */ +/** Full path to program executable. */ +static char bprogname[FILE_MAX]; +/** Full path to directory in which executable is located. */ +static char bprogdir[FILE_MAX]; +/** Persistent temporary directory. */ +static char btempdir_base[FILE_MAX]; +/** Volatile temporary directory (owned by Blender, removed on exit). */ +static char btempdir_session[FILE_MAX] = ""; + +/** + * This is now only used to really get the user's default document folder. + * + * \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 @@ -84,17 +91,17 @@ const char *BKE_appdir_folder_default(void) static char documentfolder[MAXPATHLEN]; HRESULT hResult; - /* Check for %HOME% env var */ + /* Check for `%HOME%` environment variable. */ if (uput_getenv("HOME", documentfolder, MAXPATHLEN)) { if (BLI_is_dir(documentfolder)) { return documentfolder; } } - /* add user profile support for WIN 2K / NT. - * This is %APPDATA%, which translates to either - * %USERPROFILE%\Application Data or since Vista - * to %USERPROFILE%\AppData\Roaming + /* Add user profile support for WIN 2K / NT. + * This is `%APPDATA%`, which translates to either: + * - `%USERPROFILE%\Application Data` or... + * - `%USERPROFILE%\AppData\Roaming` (since Vista). */ hResult = SHGetFolderPath(NULL, CSIDL_PERSONAL, NULL, SHGFP_TYPE_CURRENT, documentfolder); @@ -110,7 +117,9 @@ const char *BKE_appdir_folder_default(void) // #define PATH_DEBUG -/* returns a formatted representation of the specified version number. Non-re-entrant! */ +/** + * \returns a formatted representation of the specified version number. Non-re-entrant! + */ static char *blender_version_decimal(const int ver) { static char version_str[5]; @@ -145,7 +154,7 @@ static bool test_path(char *targetpath, else { BLI_strncpy(targetpath, tmppath, targetpath_len); } - /* FIXME: why is "//" on front of \a tmppath expanded to "/" (by BLI_join_dirfile) + /* FIXME: why is "//" on front of \a tmppath expanded to "/" (by #BLI_join_dirfile) * if folder_name is specified but not otherwise? */ if (BLI_is_dir(targetpath)) { @@ -192,10 +201,10 @@ static bool test_env_path(char *path, const char *envvar) * Constructs in \a targetpath the name of a directory relative to a version-specific * sub-directory in the parent directory of the Blender executable. * - * \param targetpath: String to return path - * \param folder_name: Optional folder name within version-specific directory - * \param subfolder_name: Optional subfolder name within folder_name - * \param ver: To construct name of version-specific directory within bprogdir + * \param targetpath: String to return path. + * \param folder_name: Optional folder name within version-specific directory. + * \param subfolder_name: Optional sub-folder name within folder_name. + * \param ver: To construct name of version-specific directory within #bprogdir. * \return true if such a directory exists. */ static bool get_path_local(char *targetpath, @@ -222,10 +231,10 @@ static bool get_path_local(char *targetpath, relfolder[0] = '\0'; } - /* Try EXECUTABLE_DIR/2.5x/folder_name - - * new default directory for local blender installed files. */ + /* Try `{bprogdir}/2.xx/{folder_name}` the default directory + * for a portable distribution. See `WITH_INSTALL_PORTABLE` build-option. */ #ifdef __APPLE__ - /* Due new codesign situation in OSX > 10.9.5 + /* Due new code-sign situation in OSX > 10.9.5 * we must move the blender_version dir with contents to Resources. */ char osx_resourses[FILE_MAX]; BLI_snprintf(osx_resourses, sizeof(osx_resourses), "%s../Resources", bprogdir); @@ -239,12 +248,12 @@ static bool get_path_local(char *targetpath, } /** - * Is this an install with user files kept together with the Blender executable and its - * installation files. + * 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 */ + /* Detect portable install by the existence of `config` folder. */ const int ver = BLENDER_VERSION; char path[FILE_MAX]; @@ -252,10 +261,10 @@ bool BKE_appdir_app_is_portable_install(void) } /** - * Returns the path of a folder from environment variables + * Returns the path of a folder from environment variables. * * \param targetpath: String to return path. - * \param subfolder_name: optional name of subfolder within folder. + * \param subfolder_name: optional name of sub-folder within folder. * \param envvar: name of environment variable to check folder_name. * \return true if it was able to construct such a path and the path exists. */ @@ -277,10 +286,10 @@ static bool get_path_environment(char *targetpath, } /** - * Returns the path of a folder from environment variables + * Returns the path of a folder from environment variables. * * \param targetpath: String to return path. - * \param subfolder_name: optional name of subfolder within folder. + * \param subfolder_name: optional name of sub-folder within folder. * \param envvar: name of environment variable to check folder_name. * \return true if it was able to construct such a path. */ @@ -304,10 +313,11 @@ static bool get_path_environment_notest(char *targetpath, /** * Returns the path of a folder within the user-files area. - * \param targetpath: String to return path - * \param folder_name: default name of folder within user area - * \param subfolder_name: optional name of subfolder within folder - * \param ver: Blender version, used to construct a sub-directory name + * + * \param targetpath: String to return path. + * \param folder_name: default name of folder within user area. + * \param subfolder_name: optional name of sub-folder within folder. + * \param ver: Blender version, used to construct a sub-directory name. * \return true if it was able to construct such a path. */ static bool get_path_user(char *targetpath, @@ -348,10 +358,10 @@ static bool get_path_user(char *targetpath, /** * Returns the path of a folder within the Blender installation directory. * - * \param targetpath: String to return path - * \param folder_name: default name of folder within installation area - * \param subfolder_name: optional name of sub-folder within folder - * \param ver: Blender version, used to construct a sub-directory name + * \param targetpath: String to return path. + * \param folder_name: default name of folder within installation area. + * \param subfolder_name: optional name of sub-folder within folder. + * \param ver: Blender version, used to construct a sub-directory name. * \return true if it was able to construct such a path. */ static bool get_path_system(char *targetpath, @@ -391,20 +401,20 @@ static bool get_path_system(char *targetpath, #endif if (subfolder_name) { - /* try $BLENDERPATH/folder_name/subfolder_name */ + /* Try `$BLENDERPATH/folder_name/subfolder_name`. */ return test_path(targetpath, targetpath_len, system_path, folder_name, subfolder_name); } - /* try $BLENDERPATH/folder_name */ + /* Try `$BLENDERPATH/folder_name`. */ return test_path(targetpath, targetpath_len, system_path, NULL, folder_name); } /** - * Get a folder out of the 'folder_id' presets for paths. - * returns the path if found, NULL string if not + * 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. */ const char *BKE_appdir_folder_id_ex(const int folder_id, const char *subfolder, @@ -569,7 +579,7 @@ const char *BKE_appdir_folder_id_create(const int folder_id, const char *subfold { const char *path; - /* only for user folders */ + /* Only for user folders. */ if (!ELEM(folder_id, BLENDER_USER_DATAFILES, BLENDER_USER_CONFIG, @@ -631,20 +641,20 @@ const char *BKE_appdir_folder_id_version(const int folder_id, const int ver, con /** * Checks if name is a fully qualified filename to an executable. - * If not it searches $PATH for the file. On Windows it also - * adds the correct extension (.com .exe etc) from - * $PATHEXT if necessary. Also on Windows it translates + * If not it searches `$PATH` for the file. On Windows it also + * adds the correct extension (`.com` `.exe` etc) from + * `$PATHEXT` if necessary. Also on Windows it translates * the name to its 8.3 version to prevent problems with * spaces and stuff. Final result is returned in \a fullname. * * \param fullname: The full path and full name of the executable - * (must be FILE_MAX minimum) - * \param name: The name of the executable (usually argv[0]) to be checked + * (must be #FILE_MAX minimum) + * \param name: The name of the executable (usually `argv[0]`) to be checked */ static void where_am_i(char *fullname, const size_t maxlen, const char *name) { #ifdef WITH_BINRELOC - /* linux uses binreloc since argv[0] is not reliable, call br_init( NULL ) first */ + /* Linux uses `binreloc` since `argv[0]` is not reliable, call `br_init(NULL)` first. */ { const char *path = NULL; path = br_find_exe(NULL); @@ -674,7 +684,7 @@ static void where_am_i(char *fullname, const size_t maxlen, const char *name) } #endif - /* unix and non linux */ + /* Unix and non Linux. */ if (name && name[0]) { BLI_strncpy(fullname, name, maxlen); @@ -685,7 +695,7 @@ static void where_am_i(char *fullname, const size_t maxlen, const char *name) #endif } else if (BLI_path_slash_rfind(name)) { - // full path + /* Full path. */ BLI_strncpy(fullname, name, maxlen); #ifdef _WIN32 BLI_path_program_extensions_add_win32(fullname, maxlen); @@ -733,12 +743,12 @@ bool BKE_appdir_program_python_search(char *fullpath, const int version_minor) { #ifdef PYTHON_EXECUTABLE_NAME - /* passed in from the build-systems 'PYTHON_EXECUTABLE' */ + /* Passed in from the build-systems 'PYTHON_EXECUTABLE'. */ const char *python_build_def = STRINGIFY(PYTHON_EXECUTABLE_NAME); #endif const char *basename = "python"; char python_ver[16]; - /* check both possible names */ + /* Check both possible names. */ const char *python_names[] = { #ifdef PYTHON_EXECUTABLE_NAME python_build_def, @@ -831,7 +841,7 @@ bool BKE_appdir_app_template_id_search(const char *app_template, char *path, siz bool BKE_appdir_app_template_has_userpref(const char *app_template) { - /* Test if app template provides a userpref.blend. + /* Test if app template provides a `userpref.blend`. * If not, we will share user preferences with the rest of Blender. */ if (!app_template && app_template[0]) { return false; @@ -913,7 +923,7 @@ static void where_is_temp(char *fullname, char *basename, const size_t maxlen, c #endif }; for (int i = 0; i < ARRAY_SIZE(env_vars); i++) { - const char *tmp = BLI_getenv(env_vars[i]); /* Windows */ + const char *tmp = BLI_getenv(env_vars[i]); if (tmp && (tmp[0] != '\0') && BLI_is_dir(tmp)) { BLI_strncpy(fullname, tmp, maxlen); break; @@ -931,7 +941,7 @@ static void where_is_temp(char *fullname, char *basename, const size_t maxlen, c /* Now that we have a valid temp dir, add system-generated unique sub-dir. */ if (basename) { - /* 'XXXXXX' is kind of tag to be replaced by mktemp-familly by an uuid. */ + /* 'XXXXXX' is kind of tag to be replaced by `mktemp-family` by an UUID. */ char *tmp_name = BLI_strdupcat(fullname, "blender_XXXXXX"); const size_t ln = strlen(tmp_name) + 1; if (ln <= maxlen) { @@ -961,9 +971,9 @@ static void where_is_temp(char *fullname, char *basename, const size_t maxlen, c } /** - * Sets btempdir_base to userdir if specified and is a valid directory, otherwise - * chooses a suitable OS-specific temporary directory. - * Sets btempdir_session to a #mkdtemp generated sub-dir of btempdir_base. + * Sets #btempdir_base to \a userdir if specified and is a valid directory, + * otherwise chooses a suitable OS-specific temporary directory. + * Sets #btempdir_session to a #mkdtemp generated sub-dir of #btempdir_base. */ void BKE_tempdir_init(const char *userdir) { @@ -996,8 +1006,9 @@ void BKE_tempdir_session_purge(void) } } -/* Gets a good default directory for fonts */ - +/** + * Gets a good default directory for fonts. + */ bool BKE_appdir_font_folder_default( /* This parameter can only be `const` on non-windows platforms. * NOLINTNEXTLINE: readability-non-const-parameter. */ -- cgit v1.2.3