patch [#34103]

from Lawrence D'Oliveiro (ldo)

More use of bool type, necessitating adding inclusion of BLI_utildefines.h, or moving it up in the inclusion order if it was already included, in various places
- storage.c: make some variables only used in bli_builddir local to that
- storage.c: BLI_file_descriptor_size should allow 0 as a valid file descriptor
- path_util.c: make pointers to non-reentrant storage returned from folder routines const, necessitating making variables holding these returned pointers const elsewhere as well
- path_util.c: BLI_string_to_utf8 closes iconv context in case of conversion error
-  blf_lang.c: fill_locales routine now has its own "languages" local variable to construct paths (was stealing internal storage belonging to BLI_get_folder before)

24 files changed, 387 insertions, 156 deletions

diff --git a/source/blender/blenfont/intern/blf_dir.c b/source/blender/blenfont/intern/blf_dir.c
index b6a98faa48c..116a55c0579 100644
--- a/source/blender/blenfont/intern/blf_dir.c
+++ b/source/blender/blenfont/intern/blf_dir.c
@@ -41,6 +41,7 @@
 
 #include "DNA_vec_types.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 #include "BLI_listbase.h"
 #include "BLI_path_util.h"
diff --git a/source/blender/blenfont/intern/blf_lang.c b/source/blender/blenfont/intern/blf_lang.c
index 73294f1aed6..d1c037b0358 100644
--- a/source/blender/blenfont/intern/blf_lang.c
+++ b/source/blender/blenfont/intern/blf_lang.c
@@ -78,15 +78,16 @@ static void free_locales(void)
 
 static void fill_locales(void)
 {
-	char *languages_path = BLI_get_folder(BLENDER_DATAFILES, "locale");
+	const char * const languages_path = BLI_get_folder(BLENDER_DATAFILES, "locale");
+	char languages[FILE_MAX];
 	LinkNode *lines = NULL, *line;
 	char *str;
 	int idx = 0;
 
 	free_locales();
 
-	BLI_join_dirfile(languages_path, FILE_MAX, languages_path, "languages");
-	line = lines = BLI_file_read_as_lines(languages_path);
+	BLI_join_dirfile(languages, FILE_MAX, languages_path, "languages");
+	line = lines = BLI_file_read_as_lines(languages);
 
 	/* This whole "parsing" code is a bit weak, in that it expects strictly formated input file...
 	 * Should not be a problem, though, as this file is script-generated! */
@@ -185,7 +186,7 @@ EnumPropertyItem *BLF_RNA_lang_enum_properties(void)
 void BLF_lang_init(void)
 {
 #ifdef WITH_INTERNATIONAL
-	char *messagepath = BLI_get_folder(BLENDER_DATAFILES, "locale");
+	const char * const messagepath = BLI_get_folder(BLENDER_DATAFILES, "locale");
 
 	if (messagepath) {
 		bl_locale_init(messagepath, TEXT_DOMAIN_NAME);
diff --git a/source/blender/blenfont/intern/blf_translation.c b/source/blender/blenfont/intern/blf_translation.c
index b5b72b68677..750f310fade 100644
--- a/source/blender/blenfont/intern/blf_translation.c
+++ b/source/blender/blenfont/intern/blf_translation.c
@@ -56,7 +56,7 @@ unsigned char *BLF_get_unifont(int *unifont_size_r)
 {
 #ifdef WITH_INTERNATIONAL
 	if (unifont_ttf == NULL) {
-		char *fontpath = BLI_get_folder(BLENDER_DATAFILES, "fonts");
+		const char * const fontpath = BLI_get_folder(BLENDER_DATAFILES, "fonts");
 		if (fontpath) {
 			char unifont_path[1024];
 
diff --git a/source/blender/blenkernel/intern/customdata_file.c b/source/blender/blenkernel/intern/customdata_file.c
index 78449879f72..dfaa5573562 100644
--- a/source/blender/blenkernel/intern/customdata_file.c
+++ b/source/blender/blenkernel/intern/customdata_file.c
@@ -29,9 +29,9 @@
 
 #include "MEM_guardedalloc.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 #include "BLI_string.h"
-#include "BLI_utildefines.h"
 #include "BLI_endian_switch.h"
 
 #include "BKE_customdata_file.h"
diff --git a/source/blender/blenkernel/intern/tracking.c b/source/blender/blenkernel/intern/tracking.c
index 7e2970108cd..2f813538b41 100644
--- a/source/blender/blenkernel/intern/tracking.c
+++ b/source/blender/blenkernel/intern/tracking.c
@@ -1773,6 +1773,7 @@ ImBuf *BKE_tracking_sample_pattern(int frame_width, int frame_height, ImBuf *sea
 	(void) frame_height;
 	(void) search_ibuf;
 	(void) marker;
+	(void) from_anchor;
 	(void) track;
 	(void) use_mask;
 
diff --git a/source/blender/blenlib/BLI_fileops.h b/source/blender/blenlib/BLI_fileops.h
index c278370d211..f0d4bb111a0 100644
--- a/source/blender/blenlib/BLI_fileops.h
+++ b/source/blender/blenlib/BLI_fileops.h
@@ -61,8 +61,8 @@ int    BLI_stat(const char *path, struct stat *buffer);
 
 struct direntry;
 
-int    BLI_is_dir(const char *path);
-int    BLI_is_file(const char *path);
+bool   BLI_is_dir(const char *path);
+bool   BLI_is_file(const char *path);
 void   BLI_dir_create_recursive(const char *dir);
 double BLI_dir_free_space(const char *dir);
 char  *BLI_current_working_dir(char *dir, const size_t maxlen);
@@ -85,7 +85,7 @@ size_t BLI_file_descriptor_size(int file);
 size_t BLI_file_size(const char *file);
 
 /* compare if one was last modified before the other */
-int    BLI_file_older(const char *file1, const char *file2);
+bool   BLI_file_older(const char *file1, const char *file2);
 
 /* read ascii file as lines, empty list if reading fails */
 struct LinkNode *BLI_file_read_as_lines(const char *file);
diff --git a/source/blender/blenlib/BLI_path_util.h b/source/blender/blenlib/BLI_path_util.h
index 50b6e6a1c0b..301e2c02018 100644
--- a/source/blender/blenlib/BLI_path_util.h
+++ b/source/blender/blenlib/BLI_path_util.h
@@ -40,10 +40,10 @@ struct direntry;
 
 const char *BLI_getDefaultDocumentFolder(void);
 
-char *BLI_get_folder(int folder_id, const char *subfolder);
-char *BLI_get_folder_create(int folder_id, const char *subfolder);
-char *BLI_get_user_folder_notest(int folder_id, const char *subfolder);
-char *BLI_get_folder_version(const int id, const int ver, const bool do_check);
+const char *BLI_get_folder(int folder_id, const char *subfolder);
+const char *BLI_get_folder_create(int folder_id, const char *subfolder);
+const char *BLI_get_user_folder_notest(int folder_id, const char *subfolder);
+const char *BLI_get_folder_version(const int id, const int ver, const bool do_check);
 
 /* folder_id */
 
@@ -109,8 +109,8 @@ void BLI_getlastdir(const char *dir, char *last, size_t maxlen);
 bool BLI_testextensie(const char *str, const char *ext);
 bool BLI_testextensie_array(const char *str, const char **ext_array);
 bool BLI_testextensie_glob(const char *str, const char *ext_fnmatch);
-int BLI_replace_extension(char *path, size_t maxlen, const char *ext);
-int BLI_ensure_extension(char *path, size_t maxlen, const char *ext);
+bool BLI_replace_extension(char *path, size_t maxlen, const char *ext);
+bool BLI_ensure_extension(char *path, size_t maxlen, const char *ext);
 void BLI_uniquename(struct ListBase *list, void *vlink, const char * defname, char delim, short name_offs, short len);
 bool BLI_uniquename_cb(bool (*unique_check)(void * arg, const char * name),
                        void *arg, const char * defname, char delim, char *name, short name_len);
@@ -155,13 +155,14 @@ bool BLI_has_parent(char *path);
  * \retval Returns true if the path was relative (started with "//").
  */
 bool BLI_path_abs(char *path, const char *basepath);
-int BLI_path_frame(char *path, int frame, int digits);
-int BLI_path_frame_range(char *path, int sta, int end, int digits);
-int BLI_path_cwd(char *path);
+bool BLI_path_frame(char *path, int frame, int digits);
+bool BLI_path_frame_range(char *path, int sta, int end, int digits);
+bool BLI_path_cwd(char *path);
 void BLI_path_rel(char *file, const char *relfile);
 
 bool BLI_path_is_rel(const char *path);
 
+/* path string comparisons: case-insensitive for Windows, case-sensitive otherwise */
 #ifdef WIN32
 #  define BLI_path_cmp BLI_strcasecmp
 #  define BLI_path_ncmp BLI_strncasecmp
diff --git a/source/blender/blenlib/BLI_utildefines.h b/source/blender/blenlib/BLI_utildefines.h
index bbafd28ddbc..7c68895b53f 100644
--- a/source/blender/blenlib/BLI_utildefines.h
+++ b/source/blender/blenlib/BLI_utildefines.h
@@ -167,7 +167,7 @@ typedef bool _BLI_Bool;
 	(b) = (tval);                 \
 } (void)0
 
-
+/* ELEM#(a, ...): is the first arg equal any of the others */
 #define ELEM(a, b, c)           ((a) == (b) || (a) == (c))
 #define ELEM3(a, b, c, d)       (ELEM(a, b, c) || (a) == (d) )
 #define ELEM4(a, b, c, d, e)    (ELEM(a, b, c) || ELEM(a, d, e) )
diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c
index 76021966d77..7399a355664 100644
--- a/source/blender/blenlib/intern/path_util.c
+++ b/source/blender/blenlib/intern/path_util.c
@@ -79,8 +79,8 @@
 /* local */
 #define UNIQUE_NAME_MAX 128
 
-static char bprogname[FILE_MAX];    /* path to program executable */
-static char bprogdir[FILE_MAX];     /* path in which executable is located */
+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[FILE_MAX];     /* temporary directory */
 
 static int add_win32_extension(char *name);
@@ -229,7 +229,7 @@ void BLI_newname(char *name, int add)
  * Ensures name is unique (according to criteria specified by caller in unique_check callback),
  * incrementing its numeric suffix as necessary. Returns true if name had to be adjusted.
  *
- * \param unique_check  Return true iff name is not unique
+ * \param unique_check  Return true if name is not unique
  * \param arg  Additional arg to unique_check--meaning is up to caller
  * \param defname  To initialize name if latter is empty
  * \param delim  Delimits numeric suffix in name
@@ -470,6 +470,10 @@ bool BLI_path_is_rel(const char *path)
 	return path[0] == '/' && path[1] == '/';
 }
 
+/**
+ * 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)
 {
 	const char *lslash;
@@ -575,8 +579,8 @@ void BLI_path_rel(char *file, const char *relfile)
 }
 
 /**
- * Cleans path and makes sure it ends with a slash, and returns true iff
- * it has more than one other path separator in it.
+ * Cleans path and makes sure it ends with a slash.
+ * \return  true if \a path has more than one other path separator in it.
  */
 bool BLI_has_parent(char *path)
 {
@@ -594,7 +598,7 @@ bool BLI_has_parent(char *path)
 }
 
 /**
- * Replaces path with the path of its parent directory, returning true iff
+ * Replaces path with the path of its parent directory, returning true if
  * it was able to find a parent directory within the pathname.
  */
 bool BLI_parent_dir(char *path)
@@ -618,7 +622,7 @@ bool BLI_parent_dir(char *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 iff 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)
 {
@@ -674,7 +678,11 @@ static void ensure_digits(char *path, int digits)
 	}
 }
 
-int BLI_path_frame(char *path, int frame, int digits)
+/**
+ * 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)
 {
 	int ch_sta, ch_end;
 
@@ -685,12 +693,17 @@ int BLI_path_frame(char *path, int frame, int digits)
 		char tmp[FILE_MAX];
 		sprintf(tmp, "%.*s%.*d%s", ch_sta, path, ch_end - ch_sta, frame, path + ch_end);
 		strcpy(path, tmp);
-		return 1;
+		return true;
 	}
-	return 0;
+	return false;
 }
 
-int BLI_path_frame_range(char *path, int sta, int end, int digits)
+/**
+ * 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.
+ */
+bool BLI_path_frame_range(char *path, int sta, int end, int digits)
 {
 	int ch_sta, ch_end;
 
@@ -703,15 +716,15 @@ int BLI_path_frame_range(char *path, int sta, int end, int digits)
 		             "%.*s%.*d-%.*d%s",
 		             ch_sta, path, ch_end - ch_sta, sta, ch_end - ch_sta, end, path + ch_end);
 		BLI_strncpy(path, tmp, FILE_MAX);
-		return 1;
+		return true;
 	}
-	return 0;
+	return false;
 }
 
 /**
  * If path begins with "//", strips that and replaces it with basepath directory. Also converts
  * a drive-letter prefix to something more sensible if this is a non-drive-letter-based system.
- * Returns true iff "//" prefix expansion was done.
+ * Returns true if "//" prefix expansion was done.
  */
 bool BLI_path_abs(char *path, const char *basepath)
 {
@@ -809,24 +822,27 @@ bool BLI_path_abs(char *path, const char *basepath)
 }
 
 
-/*
- * Should only be done with command line paths.
- * this is NOT something blenders internal paths support like the // prefix
+/**
+ * Expands path relative to the current working directory, if it was relative.
+ * Returns true if such expansion was done.
+ *
+ * \note Should only be done with command line paths.
+ * this is _not_ something blenders internal paths support like the "//" prefix
  */
-int BLI_path_cwd(char *path)
+bool BLI_path_cwd(char *path)
 {
-	int wasrelative = 1;
-	int filelen = strlen(path);
+	bool wasrelative = true;
+	const int filelen = strlen(path);
 	
 #ifdef WIN32
 	if (filelen >= 3 && path[1] == ':' && (path[2] == '\\' || path[2] == '/'))
-		wasrelative = 0;
+		wasrelative = false;
 #else
 	if (filelen >= 2 && path[0] == '/')
-		wasrelative = 0;
+		wasrelative = false;
 #endif
 	
-	if (wasrelative == 1) {
+	if (wasrelative) {
 		char cwd[FILE_MAX] = "";
 		BLI_current_working_dir(cwd, sizeof(cwd)); /* in case the full path to the blend isn't used */
 		
@@ -853,6 +869,7 @@ int BLI_path_cwd(char *path)
 
 
 /* 'di's filename component is moved into 'fi', di is made a dir path */
+/* FIXME: duplicates functionality of BLI_split_dirfile. */
 void BLI_splitdirstring(char *di, char *fi)
 {
 	char *lslash = (char *)BLI_last_slash(di);
@@ -867,6 +884,9 @@ void BLI_splitdirstring(char *di, char *fi)
 	}
 }
 
+/**
+ * Copies into *last the part of *dir following the second-last slash.
+ */
 void BLI_getlastdir(const char *dir, char *last, const size_t maxlen)
 {
 	const char *s = dir;
@@ -893,7 +913,7 @@ void BLI_getlastdir(const char *dir, char *last, const size_t maxlen)
 const char *BLI_getDefaultDocumentFolder(void)
 {
 #ifndef WIN32
-	const char *xdg_documents_dir = getenv("XDG_DOCUMENTS_DIR");
+	const char * const xdg_documents_dir = getenv("XDG_DOCUMENTS_DIR");
 
 	if (xdg_documents_dir)
 		return xdg_documents_dir;
@@ -929,6 +949,7 @@ const char *BLI_getDefaultDocumentFolder(void)
 
 // #define PATH_DEBUG
 
+/* returns a formatted representation of the specified version number. Non-reentrant! */
 static char *blender_version_decimal(const int ver)
 {
 	static char version_str[5];
@@ -936,7 +957,11 @@ static char *blender_version_decimal(const int ver)
 	return version_str;
 }
 
-static int test_path(char *targetpath, const char *path_base, const char *path_sep, const char *folder_name)
+/**
+ * Concatenates path_base, (optional) path_sep and (optional) folder_name into targetpath,
+ * returning true if result points to a directory.
+ */
+static bool test_path(char *targetpath, const char *path_base, const char *path_sep, const char *folder_name)
 {
 	char tmppath[FILE_MAX];
 	
@@ -948,44 +973,60 @@ static int test_path(char *targetpath, const char *path_base, const char *path_s
 		BLI_make_file_string("/", targetpath, tmppath, folder_name);
 	else
 		BLI_strncpy(targetpath, tmppath, sizeof(tmppath));
+	/* FIXME: why is "//" on front of tmppath expanded to "/" (by BLI_join_dirfile)
+	 * if folder_name is specified but not otherwise? */
 
 	if (BLI_is_dir(targetpath)) {
 #ifdef PATH_DEBUG
 		printf("\t%s found: %s\n", __func__, targetpath);
 #endif
-		return 1;
+		return true;
 	}
 	else {
 #ifdef PATH_DEBUG
 		printf("\t%s missing: %s\n", __func__, targetpath);
 #endif
 		//targetpath[0] = '\0';
-		return 0;
+		return false;
 	}
 }
 
-static int test_env_path(char *path, const char *envvar)
+/**
+ * Puts the value of the specified environment variable into *path if it exists
+ * and points at a directory. Returns true if this was done.
+ */
+static bool test_env_path(char *path, const char *envvar)
 {
 	const char *env = envvar ? getenv(envvar) : NULL;
-	if (!env) return 0;
+	if (!env) return false;
 	
 	if (BLI_is_dir(env)) {
 		BLI_strncpy(path, env, FILE_MAX);
 #ifdef PATH_DEBUG
 		printf("\t%s env %s found: %s\n", __func__, envvar, env);
 #endif
-		return 1;
+		return true;
 	}
 	else {
 		path[0] = '\0';
 #ifdef PATH_DEBUG
 		printf("\t%s env %s missing: %s\n", __func__, envvar, env);
 #endif
-		return 0;
+		return false;
 	}
 }
 
-static int get_path_local(char *targetpath, const char *folder_name, const char *subfolder_name, const int ver)
+/**
+ * Constructs in \a targetpath the name of a directory relative to a version-specific
+ * subdirectory 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
+ * \return true if such a directory exists.
+ */
+static bool get_path_local(char *targetpath, const char *folder_name, const char *subfolder_name, const int ver)
 {
 	char relfolder[FILE_MAX];
 	
@@ -1006,22 +1047,34 @@ static int get_path_local(char *targetpath, const char *folder_name, const char
 	}
 
 	/* try EXECUTABLE_DIR/2.5x/folder_name - new default directory for local blender installed files */
-	if (test_path(targetpath, bprogdir, blender_version_decimal(ver), relfolder))
-		return 1;
-
-	return 0;
+	return test_path(targetpath, bprogdir, blender_version_decimal(ver), relfolder);
 }
 
-static int is_portable_install(void)
+/**
+ * Is this an install with user files kept together with the Blender executable and its
+ * installation files.
+ */
+static bool is_portable_install(void)
 {
-	/* detect portable install by the existance of config folder */
+	/* detect portable install by the existence of config folder */
 	const int ver = BLENDER_VERSION;
 	char path[FILE_MAX];
 
 	return get_path_local(path, "config", NULL, ver);
 }
 
-static int get_path_user(char *targetpath, const char *folder_name, const char *subfolder_name, const char *envvar, const int ver)
+/**
+ * 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 envvar  name of environment variable which, if defined, overrides folder_name
+ * \param ver  Blender version, used to construct a subdirectory name
+ * \return true if it was able to construct such a path.
+ */
+static bool get_path_user(char *targetpath, const char *folder_name, const char *subfolder_name, const char *envvar, const int ver)
 {
 	char user_path[FILE_MAX];
 	const char *user_base_path;
@@ -1038,7 +1091,7 @@ static int get_path_user(char *targetpath, const char *folder_name, const char *
 		}
 		else {
 			BLI_strncpy(targetpath, user_path, FILE_MAX);
-			return 1;
+			return true;
 		}
 	}
 
@@ -1047,30 +1100,34 @@ static int get_path_user(char *targetpath, const char *folder_name, const char *
 		BLI_strncpy(user_path, user_base_path, FILE_MAX);
 
 	if (!user_path[0])
-		return 0;
+		return false;
 	
 #ifdef PATH_DEBUG
 	printf("%s: %s\n", __func__, user_path);
 #endif
 	
 	if (subfolder_name) {
-		/* try $HOME/folder_name/subfolder_name */
 		return test_path(targetpath, user_path, folder_name, subfolder_name);
 	}
 	else {
-		/* try $HOME/folder_name */
 		return test_path(targetpath, user_path, NULL, folder_name);
 	}
 }
 
-static int get_path_system(char *targetpath, const char *folder_name, const char *subfolder_name, const char *envvar, const int ver)
+/**
+ * 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 subfolder within folder
+ * \param envvar  name of environment variable which, if defined, overrides folder_name
+ * \param ver  Blender version, used to construct a subdirectory name
+ * \return  true if it was able to construct such a path.
+ */
+static bool get_path_system(char *targetpath, const char *folder_name, const char *subfolder_name, const char *envvar, const int ver)
 {
 	char system_path[FILE_MAX];
 	const char *system_base_path;
-
-
-	/* first allow developer only overrides to the system path
-	 * these are only used when running blender from source */
 	char cwd[FILE_MAX];
 	char relfolder[FILE_MAX];
 
@@ -1086,16 +1143,20 @@ static int get_path_system(char *targetpath, const char *folder_name, const char
 		relfolder[0] = '\0';
 	}
 
+	/* first allow developer only overrides to the system path
+	 * these are only used when running blender from source */
+
 	/* try CWD/release/folder_name */
 	if (BLI_current_working_dir(cwd, sizeof(cwd))) {
 		if (test_path(targetpath, cwd, "release", relfolder)) {
-			return 1;
+			return true;
 		}
 	}
 
 	/* try EXECUTABLE_DIR/release/folder_name */
 	if (test_path(targetpath, bprogdir, "release", relfolder))
-		return 1;
+		return true;
+
 	/* end developer overrides */
 
 
@@ -1108,7 +1169,7 @@ static int get_path_system(char *targetpath, const char *folder_name, const char
 		}
 		else {
 			BLI_strncpy(targetpath, system_path, FILE_MAX);
-			return 1;
+			return true;
 		}
 	}
 
@@ -1117,7 +1178,7 @@ static int get_path_system(char *targetpath, const char *folder_name, const char
 		BLI_strncpy(system_path, system_base_path, FILE_MAX);
 	
 	if (!system_path[0])
-		return 0;
+		return false;
 	
 #ifdef PATH_DEBUG
 	printf("%s: %s\n", __func__, system_path);
@@ -1135,7 +1196,7 @@ static int get_path_system(char *targetpath, const char *folder_name, const char
 
 /* get a folder out of the 'folder_id' presets for paths */
 /* returns the path if found, NULL string if not */
-char *BLI_get_folder(int folder_id, const char *subfolder)
+const char *BLI_get_folder(int folder_id, const char *subfolder)
 {
 	const int ver = BLENDER_VERSION;
 	static char path[FILE_MAX] = "";
@@ -1182,7 +1243,10 @@ char *BLI_get_folder(int folder_id, const char *subfolder)
 	return path;
 }
 
-char *BLI_get_user_folder_notest(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 *BLI_get_user_folder_notest(int folder_id, const char *subfolder)
 {
 	const int ver = BLENDER_VERSION;
 	static char path[FILE_MAX] = "";
@@ -1207,9 +1271,12 @@ char *BLI_get_user_folder_notest(int folder_id, const char *subfolder)
 	return path;
 }
 
-char *BLI_get_folder_create(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 *BLI_get_folder_create(int folder_id, const char *subfolder)
 {
-	char *path;
+	const char *path;
 
 	/* only for user folders */
 	if (!ELEM4(folder_id, BLENDER_USER_DATAFILES, BLENDER_USER_CONFIG, BLENDER_USER_SCRIPTS, BLENDER_USER_AUTOSAVE))
@@ -1225,10 +1292,14 @@ char *BLI_get_folder_create(int folder_id, const char *subfolder)
 	return path;
 }
 
-char *BLI_get_folder_version(const int id, const int ver, const bool do_check)
+/**
+ * Returns the path of the top-level version-specific local, user or system directory.
+ * If do_check, then the result will be NULL if the directory doesn't exist.
+ */
+const char *BLI_get_folder_version(const int id, const int ver, const bool do_check)
 {
 	static char path[FILE_MAX] = "";
-	int ok;
+	bool ok;
 	switch (id) {
 		case BLENDER_RESOURCE_PATH_USER:
 			ok = get_path_user(path, NULL, NULL, NULL, ver);
@@ -1241,11 +1312,11 @@ char *BLI_get_folder_version(const int id, const int ver, const bool do_check)
 			break;
 		default:
 			path[0] = '\0'; /* in case do_check is false */
-			ok = FALSE;
+			ok = false;
 			BLI_assert(!"incorrect ID");
 	}
 
-	if ((ok == FALSE) && do_check) {
+	if (!ok && do_check) {
 		return NULL;
 	}
 
@@ -1262,6 +1333,9 @@ char *BLI_get_folder_version(const int id, const int ver, const bool do_check)
 #  undef PATH_DEBUG
 #endif
 
+/**
+ * Sets the specified environment variable to the specified value.
+ */
 void BLI_setenv(const char *env, const char *val)
 {
 	/* free windows */
@@ -1287,6 +1361,8 @@ void BLI_setenv(const char *env, const char *val)
 /**
  * Only set an env var if already not there.
  * Like Unix setenv(env, val, 0);
+ *
+ * (not used anywhere).
  */
 void BLI_setenv_if_new(const char *env, const char *val)
 {
@@ -1295,6 +1371,9 @@ void BLI_setenv_if_new(const char *env, const char *val)
 }
 
 
+/**
+ * Changes to the path separators to the native ones for this OS.
+ */
 void BLI_clean(char *path)
 {
 #ifdef WIN32
@@ -1306,6 +1385,9 @@ void BLI_clean(char *path)
 #endif
 }
 
+/**
+ * Replaces occurrences of from with to in *string.
+ */
 void BLI_char_switch(char *string, char from, char to) 
 {
 	while (*string != 0) {
@@ -1314,6 +1396,10 @@ void BLI_char_switch(char *string, char from, char to)
 	}
 }
 
+/**
+ * Strips off nonexistent subdirectories from the end of *dir, leaving the path of
+ * the lowest-level directory that does exist.
+ */
 void BLI_make_exist(char *dir)
 {
 	int a;
@@ -1322,7 +1408,7 @@ void BLI_make_exist(char *dir)
 
 	a = strlen(dir);
 
-	while (BLI_is_dir(dir) == 0) {
+	while (!BLI_is_dir(dir)) {
 		a--;
 		while (dir[a] != SEP) {
 			a--;
@@ -1342,11 +1428,14 @@ void BLI_make_exist(char *dir)
 	}
 }
 
+/**
+ * Ensures that the parent directory of *name exists.
+ */
 void BLI_make_existing_file(const char *name)
 {
 	char di[FILE_MAX], fi[FILE_MAXFILE];
-
 	BLI_strncpy(di, name, sizeof(di));
+	/* FIXME: use BLI_split_dir_part instead and get rid of fi. */
 	BLI_splitdirstring(di, fi);
 	
 	/* test exist */
@@ -1355,8 +1444,16 @@ void BLI_make_existing_file(const char *name)
 	}
 }
 
-
-void BLI_make_file_string(const char *relabase, char *string,  const char *dir, const char *file)
+/**
+ * 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
+ */
+void BLI_make_file_string(const char *relabase, char *string, const char *dir, const char *file)
 {
 	int sl;
 
@@ -1460,8 +1557,11 @@ bool BLI_testextensie_array(const char *str, const char **ext_array)
 	return false;
 }
 
-/* semicolon separated wildcards, eg:
- *  '*.zip;*.py;*.exe' */
+/**
+ * Semicolon separated wildcards, eg:
+ *  '*.zip;*.py;*.exe'
+ * does str match any of the semicolon-separated glob patterns in fnmatch.
+ */
 bool BLI_testextensie_glob(const char *str, const char *ext_fnmatch)
 {
 	const char *ext_step = ext_fnmatch;
@@ -1490,10 +1590,14 @@ bool BLI_testextensie_glob(const char *str, const char *ext_fnmatch)
 }
 
 
-int BLI_replace_extension(char *path, size_t maxlen, const char *ext)
+/**
+ * Removes any existing extension on the end of \a path and appends \a ext.
+ * \return false if there was no room.
+ */
+bool BLI_replace_extension(char *path, size_t maxlen, const char *ext)
 {
-	size_t path_len = strlen(path);
-	size_t ext_len = strlen(ext);
+	const size_t path_len = strlen(path);
+	const size_t ext_len = strlen(ext);
 	ssize_t a;
 
 	for (a = path_len - 1; a >= 0; a--) {
@@ -1507,24 +1611,26 @@ int BLI_replace_extension(char *path, size_t maxlen, const char *ext)
 	}
 
 	if (a + ext_len >= maxlen)
-		return 0;
+		return false;
 
 	memcpy(path + a, ext, ext_len + 1);
-	return 1;
+	return true;
 }
 
-/* strip's trailing '.'s and adds the extension only when needed */
-int BLI_ensure_extension(char *path, size_t maxlen, const char *ext)
+/**
+ * Strip's trailing '.'s and adds the extension only when needed
+ */
+bool BLI_ensure_extension(char *path, size_t maxlen, const char *ext)
 {
-	size_t path_len = strlen(path);
-	size_t ext_len = strlen(ext);
+	const size_t path_len = strlen(path);
+	const size_t ext_len = strlen(ext);
 	ssize_t a;
 
-	/* first check the extension is alread there */
+	/* first check the extension is already there */
 	if (    (ext_len <= path_len) &&
 	        (strcmp(path + (path_len - ext_len), ext) == 0))
 	{
-		return 1;
+		return true;
 	}
 
 	for (a = path_len - 1; a >= 0; a--) {
@@ -1538,10 +1644,10 @@ int BLI_ensure_extension(char *path, size_t maxlen, const char *ext)
 	a++;
 
 	if (a + ext_len >= maxlen)
-		return 0;
+		return false;
 
 	memcpy(path + a, ext, ext_len + 1);
-	return 1;
+	return true;
 }
 
 /* Converts "/foo/bar.txt" to "/foo/" and "bar.txt"
@@ -1553,7 +1659,7 @@ int BLI_ensure_extension(char *path, size_t maxlen, const char *ext)
 void BLI_split_dirfile(const char *string, char *dir, char *file, const size_t dirlen, const size_t filelen)
 {
 	const char *lslash_str = BLI_last_slash(string);
-	size_t lslash = lslash_str ? (size_t)(lslash_str - string) + 1 : 0;
+	const size_t lslash = lslash_str ? (size_t)(lslash_str - string) + 1 : 0;
 
 	if (dir) {
 		if (lslash) {
@@ -1569,17 +1675,26 @@ void BLI_split_dirfile(const char *string, char *dir, char *file, const size_t d
 	}
 }
 
+/**
+ * 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)
 {
 	BLI_split_dirfile(string, dir, NULL, dirlen, 0);
 }
 
+/**
+ * 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)
 {
 	BLI_split_dirfile(string, NULL, file, 0, filelen);
 }
 
-/* simple appending of filename to dir, does not check for valid path! */
+/**
+ * Simple appending of filename to dir, does not check for valid path!
+ * Puts result into *dst, which may be same area as *dir.
+ */
 void BLI_join_dirfile(char *dst, const size_t maxlen, const char *dir, const char *file)
 {
 	size_t dirlen = BLI_strnlen(dir, maxlen);
@@ -1616,7 +1731,12 @@ void BLI_join_dirfile(char *dst, const size_t maxlen, const char *dir, const cha
 	BLI_strncpy(dst + dirlen, file, maxlen - dirlen);
 }
 
-/* like pythons os.path.basename( ) */
+/**
+ * like pythons os.path.basename()
+ *
+ * \return The pointer into \a path string immediately after last slash,
+ * or start of \a path if none found.
+ */
 const char *BLI_path_basename(const char *path)
 {
 	const char * const filename = BLI_last_slash(path);
@@ -1658,11 +1778,29 @@ const char *BLI_path_basename(const char *path)
  * this function returns wrong results!
  * XXX: test on empty base_dir and return an error ?
  */
-int BLI_rebase_path(char *abs, size_t abs_len, char *rel, size_t rel_len, const char *base_dir, const char *src_dir, const char *dest_dir)
+
+/**
+ *
+ * \param abs  Optional string to return new full path
+ * \param abs_len  Size of *abs string
+ * \param rel  Optional area to return new path relative to parent directory of .blend file
+ *             (only meaningful if item is in a subdirectory thereof)
+ * \param rel_len  Size of *rel area
+ * \param base_dir  Path of .blend file
+ * \param src_dir  Original path of item (any initial "//" will be expanded to
+ *                 parent directory of .blend file)
+ * \param dest_dir  New directory into which item will be moved
+ * \return bli_rebase_state
+ *
+ * \note Not actually used anywhere!
+ */
+int BLI_rebase_path(char *abs, size_t abs_len,
+                    char *rel, size_t rel_len,
+                    const char *base_dir, const char *src_dir, const char *dest_dir)
 {
-	char path[FILE_MAX];
-	char dir[FILE_MAX];
-	char base[FILE_MAX];
+	char path[FILE_MAX];  /* original full path of item */
+	char dir[FILE_MAX];   /* directory part of src_dir */
+	char base[FILE_MAX];  /* basename part of src_dir */
 	char blend_dir[FILE_MAX];   /* directory, where current .blend file resides */
 	char dest_path[FILE_MAX];
 	char rel_dir[FILE_MAX];
@@ -1694,21 +1832,23 @@ int BLI_rebase_path(char *abs, size_t abs_len, char *rel, size_t rel_len, const
 	/* if image is "below" current .blend file directory */
 	if (!BLI_path_ncmp(path, blend_dir, len)) {
 
-		/* if image is _in_ current .blend file directory */
 		if (BLI_path_cmp(dir, blend_dir) == 0) {
+			/* image is directly in .blend file parent directory => put directly in dest_dir */
 			BLI_join_dirfile(dest_path, sizeof(dest_path), dest_dir, base);
 		}
-		/* "below" */
 		else {
+			/* "below" (in subdirectory of .blend file parent directory) => put in same relative directory structure in dest_dir */
 			/* rel = image_path_dir - blend_dir */
 			BLI_strncpy(rel_dir, dir + len, sizeof(rel_dir));
-
+			/* subdirectories relative to blend_dir */
 			BLI_join_dirfile(dest_path, sizeof(dest_path), dest_dir, rel_dir);
+			/* same subdirectories relative to dest_dir */
 			BLI_join_dirfile(dest_path, sizeof(dest_path), dest_path, base);
+			/* keeping original item basename */
 		}
 
 	}
-	/* image is out of current directory */
+	/* image is out of current directory -- just put straight in dest_dir */
 	else {
 		BLI_join_dirfile(dest_path, sizeof(dest_path), dest_dir, base);
 	}
@@ -1718,7 +1858,7 @@ int BLI_rebase_path(char *abs, size_t abs_len, char *rel, size_t rel_len, const
 
 	if (rel) {
 		strncat(rel, rel_dir, rel_len);
-		strncat(rel, base, rel_len);
+		strncat(rel, base, rel_len); /* FIXME: could overflow rel area! */
 	}
 
 	/* return 2 if (src == dest) */
@@ -1792,6 +1932,11 @@ void BLI_del_slash(char *string)
 	}
 }
 
+/**
+ * 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.
+ * Returns success/failure.
+ */
 static int add_win32_extension(char *name)
 {
 	int retval = 0;
@@ -2008,16 +2153,26 @@ static void BLI_where_is_temp(char *fullname, const size_t maxlen, char *userdir
 	}
 }
 
+/**
+ * Sets btempdir to userdir if specified and is a valid directory, otherwise
+ * chooses a suitable OS-specific temporary directory.
+ */
 void BLI_init_temporary_dir(char *userdir)
 {
 	BLI_where_is_temp(btempdir, FILE_MAX, userdir);
 }
 
+/**
+ * Returns the path to the temporary directory.
+ */
 const char *BLI_temporary_dir(void)
 {
 	return btempdir;
 }
 
+/**
+ * Puts in *dir path to OS-specific temporary directory.
+ */
 void BLI_system_temporary_dir(char *dir)
 {
 	BLI_where_is_temp(dir, FILE_MAX, NULL);
@@ -2025,6 +2180,10 @@ void BLI_system_temporary_dir(char *dir)
 
 #ifdef WITH_ICONV
 
+/**
+ * Converts a string encoded in the charset named by *code to UTF-8.
+ * Opens a new iconv context each time it is run, which is probably not the
+ * most efficient. */
 void BLI_string_to_utf8(char *original, char *utf_8, const char *code)
 {
 	size_t inbytesleft = strlen(original);
@@ -2045,6 +2204,7 @@ void BLI_string_to_utf8(char *original, char *utf_8, const char *code)
 	rv = iconv(cd, &original, &inbytesleft, &utf_8, &outbytesleft);
 	if (rv == (size_t) -1) {
 		printf("iconv Error\n");
+		iconv_close(cd);
 		return;
 	}
 	*utf_8 = '\0';
diff --git a/source/blender/blenlib/intern/storage.c b/source/blender/blenlib/intern/storage.c
index 1358fdd2a62..bf621ae8004 100644
--- a/source/blender/blenlib/intern/storage.c
+++ b/source/blender/blenlib/intern/storage.c
@@ -93,12 +93,14 @@
 
 /* vars: */
 static int totnum, actnum;
-static struct direntry *files;
+static struct direntry *files; /* array[totnum] */
 
-static struct ListBase dirbase_ = {NULL, NULL};
-static struct ListBase *dirbase = &dirbase_;
-
-/* can return NULL when the size is not big enough */
+/**
+ * Copies the current working directory into *dir (max size maxncpy), and
+ * returns a pointer to same.
+ *
+ * \note can return NULL when the size is not big enough
+ */
 char *BLI_current_working_dir(char *dir, const size_t maxncpy)
 {
 	const char *pwd = getenv("PWD");
@@ -110,26 +112,33 @@ char *BLI_current_working_dir(char *dir, const size_t maxncpy)
 	return getcwd(dir, maxncpy);
 }
 
-
+/*
+ * Ordering function for sorting lists of files/directories. Returns -1 if
+ * entry1 belongs before entry2, 0 if they are equal, 1 if they should be swapped.
+ */
 static int bli_compare(struct direntry *entry1, struct direntry *entry2)
 {
 	/* type is equal to stat.st_mode */
 
+	/* directories come before non-directories */
 	if (S_ISDIR(entry1->type)) {
 		if (S_ISDIR(entry2->type) == 0) return (-1);
 	}
 	else {
 		if (S_ISDIR(entry2->type)) return (1);
 	}
+	/* non-regular files come after regular files */
 	if (S_ISREG(entry1->type)) {
 		if (S_ISREG(entry2->type) == 0) return (-1);
 	}
 	else {
 		if (S_ISREG(entry2->type)) return (1);
 	}
+	/* arbitrary, but consistent, ordering of different types of non-regular files */
 	if ((entry1->type & S_IFMT) < (entry2->type & S_IFMT)) return (-1);
 	if ((entry1->type & S_IFMT) > (entry2->type & S_IFMT)) return (1);
-	
+
+	/* OK, now we know their S_IFMT fields are the same, go on to a name comparison */
 	/* make sure "." and ".." are always first */
 	if (strcmp(entry1->relname, ".") == 0) return (-1);
 	if (strcmp(entry2->relname, ".") == 0) return (1);
@@ -139,7 +148,10 @@ static int bli_compare(struct direntry *entry1, struct direntry *entry2)
 	return (BLI_natstrcmp(entry1->relname, entry2->relname));
 }
 
-
+/**
+ * Returns the number of free bytes on the volume containing the specified pathname. */
+/* Not actually used anywhere.
+ */
 double BLI_dir_free_space(const char *dir)
 {
 #ifdef WIN32
@@ -197,10 +209,14 @@ double BLI_dir_free_space(const char *dir)
 #endif
 }
 
+/**
+ * Scans the directory named *dirname and appends entries for its contents to files.
+ * Recorded pathnames will be prefixed by *relname if specified (FIXME: actually this
+ * option is not used anywhere, might as well get rid of it).
+ */
 static void bli_builddir(const char *dirname, const char *relname)
 {
-	struct dirent *fname;
-	struct dirlink *dlink;
+	struct ListBase dirbase = {NULL, NULL};
 	int rellen, newnum = 0;
 	char buf[256];
 	DIR *dir;
@@ -212,6 +228,9 @@ static void bli_builddir(const char *dirname, const char *relname)
 		buf[rellen] = '/';
 		rellen++;
 	}
+	/* FIXME: any reason why we can't opendir dirname directly, instead of making it
+	 * the current directory first? That would simplify calls to this routine (currently
+	 * having to save/restore the current directory) a lot. */
 #ifndef WIN32
 	if (chdir(dirname) == -1) {
 		perror(dirname);
@@ -227,13 +246,14 @@ static void bli_builddir(const char *dirname, const char *relname)
 	UTF16_UN_ENCODE(dirname);
 
 #endif
-	if ((dir = (DIR *)opendir("."))) {
-		while ((fname = (struct dirent *) readdir(dir)) != NULL) {
-			dlink = (struct dirlink *)malloc(sizeof(struct dirlink));
-			if (dlink) {
+	if ((dir = opendir(".")) != NULL) {
+		const struct dirent *fname;
+		while ((fname = readdir(dir)) != NULL) {
+			struct dirlink * const dlink = (struct dirlink *)malloc(sizeof(struct dirlink));
+			if (dlink != NULL) {
 				BLI_strncpy(buf + rellen, fname->d_name, sizeof(buf) - rellen);
 				dlink->name = BLI_strdup(buf);
-				BLI_addhead(dirbase, dlink);
+				BLI_addhead(&dirbase, dlink);
 				newnum++;
 			}
 		}
@@ -241,7 +261,7 @@ static void bli_builddir(const char *dirname, const char *relname)
 		if (newnum) {
 
 			if (files) {
-				void *tmp = realloc(files, (totnum + newnum) * sizeof(struct direntry));
+				void * const tmp = realloc(files, (totnum + newnum) * sizeof(struct direntry));
 				if (tmp) {
 					files = (struct direntry *)tmp;
 				}
@@ -255,7 +275,7 @@ static void bli_builddir(const char *dirname, const char *relname)
 				files = (struct direntry *)malloc(newnum * sizeof(struct direntry));
 
 			if (files) {
-				dlink = (struct dirlink *) dirbase->first;
+				struct dirlink * dlink = (struct dirlink *) dirbase.first;
 				while (dlink) {
 					memset(&files[actnum], 0, sizeof(struct direntry));
 					files[actnum].relname = dlink->name;
@@ -278,6 +298,8 @@ static void bli_builddir(const char *dirname, const char *relname)
 #endif
 					files[actnum].type = files[actnum].s.st_mode;
 					files[actnum].flags = 0;
+					/* FIXME: this is the only place where totnum and actnum are incremented,
+					 * so they will always be equal, might as well get rid of one */
 					totnum++;
 					actnum++;
 					dlink = dlink->next;
@@ -288,7 +310,7 @@ static void bli_builddir(const char *dirname, const char *relname)
 				exit(1);
 			}
 
-			BLI_freelist(dirbase);
+			BLI_freelist(&dirbase);
 			if (files) qsort(files, actnum, sizeof(struct direntry), (int (*)(const void *, const void *))bli_compare);
 		}
 		else {
@@ -302,12 +324,17 @@ static void bli_builddir(const char *dirname, const char *relname)
 	}
 }
 
+/**
+ * Fills in the "mode[123]", "size" and "string" fields in the elements of the files
+ * array with descriptive details about each item. "string" will have a format similar to "ls -l".
+ */
 static void bli_adddirstrings(void)
 {
 	char datum[100];
 	char buf[512];
 	char size[250];
 	static const char *types[8] = {"---", "--x", "-w-", "-wx", "r--", "r-x", "rw-", "rwx"};
+	/* symbolic display, indexed by mode field value */
 	int num, mode;
 #ifdef WIN32
 	__int64 st_size;
@@ -375,6 +402,9 @@ static void bli_adddirstrings(void)
 		 */
 		st_size = file->s.st_size;
 
+		/* FIXME: Either change decimal prefixes to binary ones
+		 * <http://en.wikipedia.org/wiki/Binary_prefix>, or change
+		 * divisor factors from 1024 to 1000. */
 		if (st_size > 1024 * 1024 * 1024) {
 			BLI_snprintf(file->size, sizeof(file->size), "%.2f GB", ((double)st_size) / (1024 * 1024 * 1024));
 		}
@@ -413,9 +443,14 @@ static void bli_adddirstrings(void)
 		             file->date, file->time, size, file->relname);
 
 		file->string = BLI_strdup(buf);
+		/* FIXME: not actually used anywhere, why bother to set it up? */
 	}
 }
 
+/**
+ * Scans the contents of the directory named *dirname, and allocates and fills in an
+ * array of entries describing them in *filelist. The length of the array is the function result.
+ */
 unsigned int BLI_dir_contents(const char *dirname,  struct direntry **filelist)
 {
 	/* reset global variables
@@ -441,17 +476,24 @@ unsigned int BLI_dir_contents(const char *dirname,  struct direntry **filelist)
 }
 
 
+/**
+ * Returns the file size of an opened file descriptor.
+ */
 size_t BLI_file_descriptor_size(int file)
 {
 	struct stat buf;
 
-	if (file <= 0) return (-1);
+	if (file < 0) return (-1);
 	fstat(file, &buf); /* CHANGE */
 	return (buf.st_size);
 }
 
+/**
+ * Returns the size of a file.
+ */
 size_t BLI_file_size(const char *path)
 {
+	/* FIXME: opening and closing the file is inefficient. Why not use stat(2) instead? */
 	int size, file = BLI_open(path, O_BINARY | O_RDONLY, 0);
 	
 	if (file == -1)
@@ -462,7 +504,10 @@ size_t BLI_file_size(const char *path)
 	return size;
 }
 
-
+/**
+ * Returns the st_mode from statting the specified path name, or 0 if it couldn't be statted
+ * (most likely doesn't exist or no access).
+ */
 int BLI_exists(const char *name)
 {
 #if defined(WIN32) 
@@ -509,18 +554,27 @@ int BLI_stat(const char *path, struct stat *buffer)
 }
 #endif
 
-/* would be better in fileops.c except that it needs stat.h so add here */
-int BLI_is_dir(const char *file)
+/**
+ * Does the specified path point to a directory?
+ * \note Would be better in fileops.c except that it needs stat.h so add here
+ */
+bool BLI_is_dir(const char *file)
 {
 	return S_ISDIR(BLI_exists(file));
 }
 
-int BLI_is_file(const char *path)
+/**
+ * Does the specified path point to a non-directory?
+ */
+bool BLI_is_file(const char *path)
 {
-	int mode = BLI_exists(path);
+	const int mode = BLI_exists(path);
 	return (mode && !S_ISDIR(mode));
 }
 
+/**
+ * Reads the contents of a text file and returns the lines in a linked list.
+ */
 LinkNode *BLI_file_read_as_lines(const char *name)
 {
 	FILE *fp = BLI_fopen(name, "r");
@@ -549,6 +603,9 @@ LinkNode *BLI_file_read_as_lines(const char *name)
 				char *line = BLI_strdupn(&buf[last], i - last);
 
 				BLI_linklist_prepend(&lines, line);
+				/* faster to build singly-linked list in reverse order */
+				/* alternatively, could process buffer in reverse order so
+				 * list ends up right way round to start with */
 				last = i + 1;
 			}
 		}
@@ -557,18 +614,22 @@ LinkNode *BLI_file_read_as_lines(const char *name)
 	}
 	
 	fclose(fp);
-	
+
+	/* get them the right way round */
 	BLI_linklist_reverse(&lines);
 	return lines;
 }
 
+/*
+ * Frees memory from a previous call to BLI_file_read_as_lines.
+ */
 void BLI_file_free_lines(LinkNode *lines)
 {
 	BLI_linklist_free(lines, (void (*)(void *))MEM_freeN);
 }
 
 /** is file1 older then file2 */
-int BLI_file_older(const char *file1, const char *file2)
+bool BLI_file_older(const char *file1, const char *file2)
 {
 #ifdef WIN32
 	struct _stat st1, st2;
@@ -576,16 +637,16 @@ int BLI_file_older(const char *file1, const char *file2)
 	UTF16_ENCODE(file1);
 	UTF16_ENCODE(file2);
 	
-	if (_wstat(file1_16, &st1)) return 0;
-	if (_wstat(file2_16, &st2)) return 0;
+	if (_wstat(file1_16, &st1)) return false;
+	if (_wstat(file2_16, &st2)) return false;
 
 	UTF16_UN_ENCODE(file2);
 	UTF16_UN_ENCODE(file1);
 #else
 	struct stat st1, st2;
 
-	if (stat(file1, &st1)) return 0;
-	if (stat(file2, &st2)) return 0;
+	if (stat(file1, &st1)) return false;
+	if (stat(file2, &st2)) return false;
 #endif
 	return (st1.st_mtime < st2.st_mtime);
 }
diff --git a/source/blender/editors/render/render_preview.c b/source/blender/editors/render/render_preview.c
index 3bf09cbbac1..2a87375dc65 100644
--- a/source/blender/editors/render/render_preview.c
+++ b/source/blender/editors/render/render_preview.c
@@ -110,7 +110,7 @@ ImBuf *get_brush_icon(Brush *brush)
 	static const int flags = IB_rect | IB_multilayer | IB_metadata;
 
 	char path[FILE_MAX];
-	char *folder;
+	const char *folder;
 
 	if (!(brush->icon_imbuf)) {
 		if (brush->flag & BRUSH_CUSTOM_ICON) {
diff --git a/source/blender/editors/space_file/filesel.c b/source/blender/editors/space_file/filesel.c
index 3c6f6358171..55d0f49912a 100644
--- a/source/blender/editors/space_file/filesel.c
+++ b/source/blender/editors/space_file/filesel.c
@@ -583,7 +583,7 @@ void file_change_dir(bContext *C, int checkdir)
 
 		ED_fileselect_clear(C, sfile);
 
-		if (checkdir && BLI_is_dir(sfile->params->dir) == 0) {
+		if (checkdir && !BLI_is_dir(sfile->params->dir)) {
 			BLI_strncpy(sfile->params->dir, filelist_dir(sfile->files), sizeof(sfile->params->dir));
 			/* could return but just refresh the current dir */
 		}
diff --git a/source/blender/editors/space_file/space_file.c b/source/blender/editors/space_file/space_file.c
index 0a4b922bb38..3d63699d5e4 100644
--- a/source/blender/editors/space_file/space_file.c
+++ b/source/blender/editors/space_file/space_file.c
@@ -629,7 +629,7 @@ void ED_spacetype_file(void)
 
 void ED_file_init(void)
 {
-	char *cfgdir = BLI_get_folder(BLENDER_USER_CONFIG, NULL);
+	const char * const cfgdir = BLI_get_folder(BLENDER_USER_CONFIG, NULL);
 	
 	fsmenu_read_system(fsmenu_get(), TRUE);
 
diff --git a/source/blender/imbuf/intern/bmp.c b/source/blender/imbuf/intern/bmp.c
index 32733668052..f19714dcd26 100644
--- a/source/blender/imbuf/intern/bmp.c
+++ b/source/blender/imbuf/intern/bmp.c
@@ -29,6 +29,7 @@
  *  \ingroup imbuf
  */
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 
 #include "imbuf.h"
diff --git a/source/blender/imbuf/intern/iris.c b/source/blender/imbuf/intern/iris.c
index 47bd3e54a6f..ac1bb246dce 100644
--- a/source/blender/imbuf/intern/iris.c
+++ b/source/blender/imbuf/intern/iris.c
@@ -32,6 +32,7 @@
 
 #include <string.h>
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/imbuf/intern/jpeg.c b/source/blender/imbuf/intern/jpeg.c
index 6a5b534c688..05495b92b98 100644
--- a/source/blender/imbuf/intern/jpeg.c
+++ b/source/blender/imbuf/intern/jpeg.c
@@ -37,6 +37,7 @@
 
 #include "MEM_guardedalloc.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_string.h"
 #include "BLI_fileops.h"
 
diff --git a/source/blender/imbuf/intern/png.c b/source/blender/imbuf/intern/png.c
index 68385f22a7a..a7e05612472 100644
--- a/source/blender/imbuf/intern/png.c
+++ b/source/blender/imbuf/intern/png.c
@@ -33,6 +33,7 @@
 
 #include "png.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 
 #include "BLI_math.h"
diff --git a/source/blender/imbuf/intern/radiance_hdr.c b/source/blender/imbuf/intern/radiance_hdr.c
index d09adeb09b5..f4ea4e74b08 100644
--- a/source/blender/imbuf/intern/radiance_hdr.c
+++ b/source/blender/imbuf/intern/radiance_hdr.c
@@ -43,6 +43,7 @@
 
 #include "MEM_guardedalloc.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 
 #include "imbuf.h"
diff --git a/source/blender/imbuf/intern/targa.c b/source/blender/imbuf/intern/targa.c
index eaad77f1ff9..156cff25e87 100644
--- a/source/blender/imbuf/intern/targa.c
+++ b/source/blender/imbuf/intern/targa.c
@@ -34,6 +34,7 @@
 #  include <io.h>
 #endif
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/python/intern/bpy.c b/source/blender/python/intern/bpy.c
index 71f85af8255..be04ee7de9a 100644
--- a/source/blender/python/intern/bpy.c
+++ b/source/blender/python/intern/bpy.c
@@ -74,7 +74,7 @@ static PyObject *bpy_script_paths(PyObject *UNUSED(self))
 {
 	PyObject *ret = PyTuple_New(2);
 	PyObject *item;
-	char *path;
+	const char *path;
 
 	path = BLI_get_folder(BLENDER_SYSTEM_SCRIPTS, NULL);
 	item = PyUnicode_DecodeFSDefault(path ? path : "");
@@ -147,7 +147,7 @@ static PyObject *bpy_user_resource(PyObject *UNUSED(self), PyObject *args, PyObj
 	int folder_id;
 	static const char *kwlist[] = {"type", "subdir", NULL};
 
-	char *path;
+	const char *path;
 
 	if (!PyArg_ParseTupleAndKeywords(args, kw, "s|s:user_resource", (char **)kwlist, &type, &subdir))
 		return NULL;
@@ -191,7 +191,7 @@ static PyObject *bpy_resource_path(PyObject *UNUSED(self), PyObject *args, PyObj
 	int major = BLENDER_VERSION / 100, minor = BLENDER_VERSION % 100;
 	static const char *kwlist[] = {"type", "major", "minor", NULL};
 	int folder_id;
-	char *path;
+	const char *path;
 
 	if (!PyArg_ParseTupleAndKeywords(args, kw, "s|ii:resource_path", (char **)kwlist, &type, &major, &minor))
 		return NULL;
@@ -245,7 +245,7 @@ void BPy_init_modules(void)
 	PyObject *mod;
 
 	/* Needs to be first since this dir is needed for future modules */
-	char *modpath = BLI_get_folder(BLENDER_SYSTEM_SCRIPTS, "modules");
+	const char * const modpath = BLI_get_folder(BLENDER_SYSTEM_SCRIPTS, "modules");
 	if (modpath) {
 		// printf("bpy: found module path '%s'.\n", modpath);
 		PyObject *sys_path = PySys_GetObject("path"); /* borrow */
diff --git a/source/blender/render/intern/source/render_result.c b/source/blender/render/intern/source/render_result.c
index c779b01afaa..ec926c3b649 100644
--- a/source/blender/render/intern/source/render_result.c
+++ b/source/blender/render/intern/source/render_result.c
@@ -35,13 +35,13 @@
 
 #include "MEM_guardedalloc.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 #include "BLI_listbase.h"
 #include "BLI_path_util.h"
 #include "BLI_rect.h"
 #include "BLI_string.h"
 #include "BLI_threads.h"
-#include "BLI_utildefines.h"
 
 #include "BKE_image.h"
 #include "BKE_global.h"
diff --git a/source/blender/windowmanager/intern/wm_files.c b/source/blender/windowmanager/intern/wm_files.c
index 45cc48c254a..699bbf52b8e 100644
--- a/source/blender/windowmanager/intern/wm_files.c
+++ b/source/blender/windowmanager/intern/wm_files.c
@@ -502,7 +502,7 @@ int wm_homefile_read(bContext *C, ReportList *UNUSED(reports), short from_memory
 
 	G.relbase_valid = 0;
 	if (!from_memory) {
-		char *cfgdir = BLI_get_folder(BLENDER_USER_CONFIG, NULL);
+		const char * const cfgdir = BLI_get_folder(BLENDER_USER_CONFIG, NULL);
 		if (cfgdir) {
 			BLI_make_file_string(G.main->name, startstr, cfgdir, BLENDER_STARTUP_FILE);
 			BLI_make_file_string(G.main->name, prefstr, cfgdir, BLENDER_USERPREF_FILE);
@@ -614,7 +614,7 @@ void wm_read_history(void)
 	struct RecentFile *recent;
 	char *line;
 	int num;
-	char *cfgdir = BLI_get_folder(BLENDER_USER_CONFIG, NULL);
+	const char * const cfgdir = BLI_get_folder(BLENDER_USER_CONFIG, NULL);
 
 	if (!cfgdir) return;
 
@@ -643,7 +643,7 @@ static void write_history(void)
 {
 	struct RecentFile *recent, *next_recent;
 	char name[FILE_MAX];
-	char *user_config_dir;
+	const char *user_config_dir;
 	FILE *fp;
 	int i;
 
diff --git a/source/blender/windowmanager/intern/wm_operators.c b/source/blender/windowmanager/intern/wm_operators.c
index 54237405273..77dc467a4e3 100644
--- a/source/blender/windowmanager/intern/wm_operators.c
+++ b/source/blender/windowmanager/intern/wm_operators.c
@@ -1598,14 +1598,14 @@ static void wm_block_splash_refreshmenu(bContext *UNUSED(C), void *UNUSED(arg_bl
 static int wm_resource_check_prev(void)
 {
 
-	char *res = BLI_get_folder_version(BLENDER_RESOURCE_PATH_USER, BLENDER_VERSION, TRUE);
+	const char *res = BLI_get_folder_version(BLENDER_RESOURCE_PATH_USER, BLENDER_VERSION, true);
 
 	// if (res) printf("USER: %s\n", res);
 
 #if 0 /* ignore the local folder */
 	if (res == NULL) {
 		/* with a local dir, copying old files isn't useful since local dir get priority for config */
-		res = BLI_get_folder_version(BLENDER_RESOURCE_PATH_LOCAL, BLENDER_VERSION, TRUE);
+		res = BLI_get_folder_version(BLENDER_RESOURCE_PATH_LOCAL, BLENDER_VERSION, true);
 	}
 #endif
 
@@ -1614,7 +1614,7 @@ static int wm_resource_check_prev(void)
 		return FALSE;
 	}
 	else {
-		return (BLI_get_folder_version(BLENDER_RESOURCE_PATH_USER, BLENDER_VERSION - 1, TRUE) != NULL);
+		return (BLI_get_folder_version(BLENDER_RESOURCE_PATH_USER, BLENDER_VERSION - 1, true) != NULL);
 	}
 }
 
@@ -2409,7 +2409,7 @@ static int blend_save_check(bContext *UNUSED(C), wmOperator *op)
 	RNA_string_get(op->ptr, "filepath", filepath);
 	if (!BLO_has_bfile_extension(filepath)) {
 		/* some users would prefer BLI_replace_extension(),
-		 * we keep getting knit-picking bug reports about this - campbell */
+		 * we keep getting nitpicking bug reports about this - campbell */
 		BLI_ensure_extension(filepath, FILE_MAX, ".blend");
 		RNA_string_set(op->ptr, "filepath", filepath);
 		return TRUE;
diff --git a/source/blender/windowmanager/intern/wm_playanim.c b/source/blender/windowmanager/intern/wm_playanim.c
index b510956dbc1..5a9d3d7d340 100644
--- a/source/blender/windowmanager/intern/wm_playanim.c
+++ b/source/blender/windowmanager/intern/wm_playanim.c
@@ -49,12 +49,12 @@
 
 #include "PIL_time.h"
 
+#include "BLI_utildefines.h"
 #include "BLI_fileops.h"
 #include "BLI_listbase.h"
 #include "BLI_path_util.h"
 #include "BLI_rect.h"
 #include "BLI_string.h"
-#include "BLI_utildefines.h"
 
 #include "IMB_imbuf_types.h"
 #include "IMB_imbuf.h"