diff options
author | Campbell Barton <ideasman42@gmail.com> | 2020-12-14 11:04:43 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2020-12-14 12:44:26 +0300 |
commit | 067046c26aaaf455c0c46470e81ac006671b8daa (patch) | |
tree | 030c2ac29f27f150c1279ce9b1d8906ef15d1d3c /source/blender | |
parent | 088df2bb03f3e8620cab9e466272850a03db5cc8 (diff) |
Cleanup: path_util.c comments
Diffstat (limited to 'source/blender')
-rw-r--r-- | source/blender/blenlib/intern/path_util.c | 79 |
1 files changed, 39 insertions, 40 deletions
diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c index 927318a923e..5636ffafb6a 100644 --- a/source/blender/blenlib/intern/path_util.c +++ b/source/blender/blenlib/intern/path_util.c @@ -288,7 +288,7 @@ void BLI_path_normalize_dir(const char *relabase, char *dir) * (good practice anyway). * REMOVED based on popular demand (see T45900). * Percent '%' char is a bit same case - not recommended to use it, - * but supported by all decent FS/OS around. + * but supported by all decent file-systems/operating-systems around. * * \note On Windows, it also ensures there is no '.' (dot char) at the end of the file, * this can lead to issues. @@ -513,8 +513,8 @@ void BLI_path_normalize_unc_16(wchar_t *path_16) #endif /** - * Replaces *file with a relative version (prefixed by "//") such that BLI_path_abs, given - * the same *relfile, will convert it back to its original value. + * Replaces `file` with a relative version (prefixed by "//") such that #BLI_path_abs, given + * the same `relfile`, will convert it back to its original value. */ void BLI_path_rel(char *file, const char *relfile) { @@ -664,7 +664,7 @@ void BLI_path_rel(char *file, const char *relfile) * \param maxlen: Maximum length of string * \param suffix: String to append to the original string * \param sep: Optional separator character - * \return true if succeeded + * \return true if succeeded */ bool BLI_path_suffix(char *string, size_t maxlen, const char *suffix, const char *sep) { @@ -703,7 +703,7 @@ bool BLI_path_suffix(char *string, size_t maxlen, const char *suffix, const char /** * Replaces path with the path of its parent directory, returning true if - * it was able to find a parent directory within the pathname. + * it was able to find a parent directory within the path. */ bool BLI_path_parent_dir(char *path) { @@ -722,7 +722,7 @@ bool BLI_path_parent_dir(char *path) } /** - * Strips off nonexistent (or non-accessible) subdirectories from the end of *dir, + * Strips off nonexistent (or non-accessible) sub-directories from the end of `dir`, * leaving the path of the lowest-level directory that does exist and we can read. */ bool BLI_path_parent_dir_until_exists(char *dir) @@ -737,9 +737,9 @@ bool BLI_path_parent_dir_until_exists(char *dir) } /** - * Looks for a sequence of "#" characters in the last slash-separated component of *path, + * Looks for a sequence of "#" characters in the last slash-separated component of `path`, * returning the indexes of the first and one past the last character in the sequence in - * *char_start and *char_end respectively. Returns true if such a sequence was found. + * `char_start` and `char_end` respectively. Returns true if such a sequence was found. */ static bool stringframe_chars(const char *path, int *char_start, int *char_end) { @@ -774,7 +774,7 @@ static bool stringframe_chars(const char *path, int *char_start, int *char_end) } /** - * Ensure *path contains at least one "#" character in its last slash-separated + * Ensure `path` contains at least one "#" character in its last slash-separated * component, appending one digits long if not. */ static void ensure_digits(char *path, int digits) @@ -796,7 +796,7 @@ static void ensure_digits(char *path, int digits) } /** - * Replaces "#" character sequence in last slash-separated component of *path + * Replaces "#" character sequence in last slash-separated component of `path` * with frame as decimal integer, with leading zeroes as necessary, to make digits digits. */ bool BLI_path_frame(char *path, int frame, int digits) @@ -818,7 +818,7 @@ bool BLI_path_frame(char *path, int frame, int digits) } /** - * Replaces "#" character sequence in last slash-separated component of *path + * Replaces "#" character sequence in last slash-separated component of `path` * with sta and end as decimal integers, with leading zeroes as necessary, to make digits * digits each, with a hyphen in-between. */ @@ -963,7 +963,7 @@ bool BLI_path_frame_check_chars(const char *path) /** * Creates a display string from path to be used menus and the user interface. - * Like bpy.path.display_name(). + * Like `bpy.path.display_name()`. */ void BLI_path_to_display_name(char *display_name, int maxlen, const char *name) { @@ -1004,7 +1004,7 @@ void BLI_path_to_display_name(char *display_name, int maxlen, const char *name) } /** - * If path begins with "//", strips that and replaces it with basepath directory. + * If path begins with "//", strips that and replaces it with `basepath` directory. * * \note Also converts drive-letter prefix to something more sensible * if this is a non-drive-letter-based system. @@ -1162,7 +1162,7 @@ bool BLI_path_abs_from_cwd(char *path, const size_t maxlen) #ifdef _WIN32 /** * Tries appending each of the semicolon-separated extensions in the PATHEXT - * environment variable (Windows-only) onto *name in turn until such a file is found. + * environment variable (Windows-only) onto `name` in turn until such a file is found. * Returns success/failure. */ bool BLI_path_program_extensions_add_win32(char *name, const size_t maxlen) @@ -1269,7 +1269,7 @@ bool BLI_path_program_search(char *fullname, const size_t maxlen, const char *na /** * Sets the specified environment variable to the specified value, - * and clears it if val == NULL. + * and clears it if `val == NULL`. */ void BLI_setenv(const char *env, const char *val) { @@ -1305,27 +1305,27 @@ void BLI_setenv_if_new(const char *env, const char *val) /** * Get an env var, result has to be used immediately. * - * On windows getenv gets its variables from a static copy of the environment variables taken at + * On windows #getenv gets its variables from a static copy of the environment variables taken at * process start-up, causing it to not pick up on environment variables created during runtime. * This function uses an alternative method to get environment variables that does pick up on * runtime environment variables. The result will be UTF-8 encoded. */ - const char *BLI_getenv(const char *env) { #ifdef _MSC_VER const char *result = NULL; - static wchar_t buffer[32768]; /* 32767 is the maximum size of the environment variable on - windows, reserve one more character for the zero terminator. */ + /* 32767 is the maximum size of the environment variable on windows, + * reserve one more character for the zero terminator. */ + static wchar_t buffer[32768]; wchar_t *env_16 = alloc_utf16_from_8(env, 0); if (env_16) { if (GetEnvironmentVariableW(env_16, buffer, ARRAY_SIZE(buffer))) { char *res_utf8 = alloc_utf_8_from_16(buffer, 0); - // make sure the result is valid, and will fit into our temporary storage buffer + /* Make sure the result is valid, and will fit into our temporary storage buffer. */ if (res_utf8) { if (strlen(res_utf8) + 1 < sizeof(buffer)) { - // We are re-using the utf16 buffer here, since allocating a second static buffer to - // contain the UTF-8 version to return would be wasteful. + /* We are re-using the utf16 buffer here, since allocating a second static buffer to + * contain the UTF-8 version to return would be wasteful. */ memcpy(buffer, res_utf8, strlen(res_utf8) + 1); result = (const char *)buffer; } @@ -1340,9 +1340,9 @@ const char *BLI_getenv(const char *env) } /** - * Ensures that the parent directory of *name exists. + * Ensures that the parent directory of `name` exists. * - * \return true on success (i.e. given path now exists on FS), false otherwise. + * \return true on success (i.e. given path now exists on file-system), false otherwise. */ bool BLI_make_existing_file(const char *name) { @@ -1354,13 +1354,13 @@ bool BLI_make_existing_file(const char *name) } /** - * Returns in *string the concatenation of *dir and *file (also with *relabase on the - * front if specified and *dir begins with "//"). Normalizes all occurrences of path - * separators, including ensuring there is exactly one between the copies of *dir and *file, - * and between the copies of *relabase and *dir. + * Returns in `string` the concatenation of `dir` and `file` (also with `relabase` on the + * front if specified and `dir` begins with "//"). Normalizes all occurrences of path + * separators, including ensuring there is exactly one between the copies of `dir` and `file`, + * and between the copies of `relabase` and `dir`. * - * \param relabase: Optional prefix to substitute for "//" on front of *dir - * \param string: Area to return result + * \param relabase: Optional prefix to substitute for "//" on front of `dir`. + * \param string: Area to return result. */ void BLI_make_file_string(const char *relabase, char *string, const char *dir, const char *file) { @@ -1500,9 +1500,8 @@ bool BLI_path_extension_check_array(const char *str, const char **ext_array) } /** - * Semicolon separated wildcards, eg: - * '*.zip;*.py;*.exe' - * does str match any of the semicolon-separated glob patterns in fnmatch. + * Semicolon separated wildcards, eg: `*.zip;*.py;*.exe` + * does str match any of the semicolon-separated glob patterns in #fnmatch. */ bool BLI_path_extension_check_glob(const char *str, const char *ext_fnmatch) { @@ -1535,7 +1534,7 @@ bool BLI_path_extension_check_glob(const char *str, const char *ext_fnmatch) * truncation. * * For now, only forbids last group to be a wildcard-only one, if there are more than one group - * (i.e. things like "*.txt;*.cpp;*" are changed to "*.txt;*.cpp;") + * (i.e. things like `*.txt;*.cpp;*` are changed to `*.txt;*.cpp;`) * * \returns true if it had to modify given \a ext_fnmatch pattern. */ @@ -1645,7 +1644,7 @@ bool BLI_path_filename_ensure(char *filepath, size_t maxlen, const char *filenam } /** - * Converts `/foo/bar.txt` to "/foo/" and `bar.txt` + * Converts `/foo/bar.txt` to `/foo/` and `bar.txt` * * - Wont change \a string. * - Wont create any directories. @@ -1678,7 +1677,7 @@ void BLI_split_dirfile( } /** - * Copies the parent directory part of string into *dir, max length dirlen. + * Copies the parent directory part of string into `dir`, max length `dirlen`. */ void BLI_split_dir_part(const char *string, char *dir, const size_t dirlen) { @@ -1686,7 +1685,7 @@ void BLI_split_dir_part(const char *string, char *dir, const size_t dirlen) } /** - * Copies the leaf filename part of string into *file, max length filelen. + * Copies the leaf filename part of string into `file`, max length `filelen`. */ void BLI_split_file_part(const char *string, char *file, const size_t filelen) { @@ -1733,7 +1732,7 @@ void BLI_path_append(char *__restrict dst, const size_t maxlen, const char *__re /** * Simple appending of filename to dir, does not check for valid path! - * Puts result into *dst, which may be same area as *dir. + * Puts result into `dst`, which may be same area as `dir`. */ void BLI_join_dirfile(char *__restrict dst, const size_t maxlen, @@ -1777,7 +1776,7 @@ void BLI_join_dirfile(char *__restrict dst, * Join multiple strings into a path, ensuring only a single path separator between each, * and trailing slash is kept. * - * \note If you want a trailing slash, add ``SEP_STR`` as the last path argument, + * \note If you want a trailing slash, add `SEP_STR` as the last path argument, * duplicate slashes will be cleaned up. */ size_t BLI_path_join(char *__restrict dst, const size_t dst_len, const char *path, ...) @@ -1861,7 +1860,7 @@ size_t BLI_path_join(char *__restrict dst, const size_t dst_len, const char *pat } /** - * like pythons os.path.basename() + * like Python's `os.path.basename()` * * \return The pointer into \a path string immediately after last slash, * or start of \a path if none found. |