[Bf-blender-cvs] [3d69ef2] master: Cleanup: BLI_path comments

[Campbell Barton]

Commit: 3d69ef240e29194cb1be9d48591e5b411152632b
Author: Campbell Barton
Date:   Sat Oct 17 16:04:54 2015 +1100
Branches: master
https://developer.blender.org/rB3d69ef240e29194cb1be9d48591e5b411152632b

Cleanup: BLI_path comments

===================================================================

M	source/blender/blenlib/BLI_path_util.h
M	source/blender/blenlib/intern/path_util.c

===================================================================

diff --git a/source/blender/blenlib/BLI_path_util.h b/source/blender/blenlib/BLI_path_util.h
index 53b3c1d..1a626ff 100644
--- a/source/blender/blenlib/BLI_path_util.h
+++ b/source/blender/blenlib/BLI_path_util.h
@@ -99,12 +99,6 @@ int BLI_stringdec(const char *string, char *head, char *start, unsigned short *n
 void BLI_stringenc(char *string, const char *head, const char *tail, unsigned short numlen, int pic);
 int BLI_split_name_num(char *left, int *nr, const char *name, const char delim);
 
-/**
- * dir can be any input, like from buttons, and this function
- * converts it to a regular full path.
- * Also removes garbage from directory paths, like /../ or double slashes etc 
- */
-
 /* removes trailing slash */
 void BLI_cleanup_file(const char *relabase, char *path) ATTR_NONNULL(2);
 /* same as above but adds a trailing slash */
@@ -118,23 +112,11 @@ bool BLI_path_make_safe(char *path) ATTR_NONNULL(1);
 /* go back one directory */
 bool BLI_parent_dir(char *path) ATTR_NONNULL();
 
-/**
- * Blender's path code replacement function.
- * Bases \a path strings leading with "//" by the
- * directory \a basepath, and replaces instances of
- * '#' with the \a framenum. Results are written
- * back into \a path.
- * 
- * \a path The path to convert
- * \a basepath The directory to base relative paths with.
- * \a framenum The framenumber to replace the frame code with.
- * \retval Returns true if the path was relative (started with "//").
- */
 bool BLI_path_abs(char *path, const char *basepath)  ATTR_NONNULL();
 bool BLI_path_frame(char *path, int frame, int digits) ATTR_NONNULL();
 bool BLI_path_frame_range(char *path, int sta, int end, int digits) ATTR_NONNULL();
 bool BLI_path_frame_get(char *path, int *r_frame, int *numdigits) ATTR_NONNULL();
-void BLI_path_frame_strip(char *path, bool setsharp, char *ext) ATTR_NONNULL();
+void BLI_path_frame_strip(char *path, bool set_frame_char, char *ext) ATTR_NONNULL();
 bool BLI_path_frame_check_chars(const char *path) ATTR_NONNULL();
 bool BLI_path_cwd(char *path, const size_t maxlen) ATTR_NONNULL();
 void BLI_path_rel(char *file, const char *relfile) ATTR_NONNULL();
@@ -179,5 +161,4 @@ bool BLI_path_suffix(char *string, size_t maxlen, const char *suffix, const char
 }
 #endif
 
-#endif
-
+#endif  /* __BLI_PATH_UTIL_H__ */
diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c
index 7a5033a..f5b3f21 100644
--- a/source/blender/blenlib/intern/path_util.c
+++ b/source/blender/blenlib/intern/path_util.c
@@ -307,14 +307,15 @@ static int BLI_path_unc_prefix_len(const char *path); /* defined below in same f
 
 /* ******************** string encoding ***************** */
 
-/* This is quite an ugly function... its purpose is to
- * take the dir name, make it absolute, and clean it up, replacing
- * excess file entry stuff (like /tmp/../tmp/../)
- * note that dir isn't protected for max string names... 
- * 
- * If relbase is NULL then its ignored
+/**
+ * Remove redundant characters from \a path and optionally make absolute.
+ *
+ * \param relbase: The path this is relative to, or ignored when NULL.
+ * \param path: Can be any input, and this function converts it to a regular full path.
+ * Also removes garbage from directory paths, like `/../` or double slashes etc.
+ *
+ * \note \a path isn't protected for max string names...
  */
-
 void BLI_cleanup_path(const char *relabase, char *path)
 {
 	ptrdiff_t a;
@@ -403,6 +404,9 @@ void BLI_cleanup_path(const char *relabase, char *path)
 #endif
 }
 
+/**
+ * Cleanup filepath ensuring a trailing slash.
+ */
 void BLI_cleanup_dir(const char *relabase, char *dir)
 {
 	BLI_cleanup_path(relabase, dir);
@@ -410,6 +414,9 @@ void BLI_cleanup_dir(const char *relabase, char *dir)
 
 }
 
+/**
+ * Cleanup filepath ensuring no trailing slash.
+ */
 void BLI_cleanup_file(const char *relabase, char *path)
 {
 	BLI_cleanup_path(relabase, path);
@@ -1063,9 +1070,14 @@ bool BLI_path_frame_check_chars(const char *path)
 }
 
 /**
- * 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 if "//" prefix expansion was done.
+ * 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.
+ *
+ * \param path: The path to convert.
+ * \param basepath: The directory to base relative paths with.
+ * \return true if the path was relative (started with "//").
  */
 bool BLI_path_abs(char *path, const char *basepath)
 {