(SDK) Document file_path.c

libretro-sdk/file/file_path.c

@@ -66,6 +66,15 @@
 #include <unistd.h>
 #endif
 
+/**
+ * path_get_extension:
+ * @path               : path
+ *
+ * Gets extension of file. Only '.'s 
+ * after the last slash are considered.
+ *
+ * Returns: extension part from the path.
+ */
 const char *path_get_extension(const char *path)
 {
    const char *ext = strrchr(path_basename(path), '.');
@@ -74,6 +83,16 @@ const char *path_get_extension(const char *path)
    return ext + 1;
 }
 
+/**
+ * path_remove_extension:
+ * @path               : path
+ *
+ * Removes the extension from the path and returns the result.
+ * Removes all text after and including the last '.'.
+ * Only '.'s after the last slash are considered.
+ *
+ * Returns: path with the extension part removed.
+ */
 char *path_remove_extension(char *path)
 {
    char *last = (char*)strrchr(path_basename(path), '.');
@@ -82,6 +101,14 @@ char *path_remove_extension(char *path)
    return last;
 }
 
+/**
+ * path_char_is_slash:
+ * @c                  : character
+ *
+ * Checks if character (@c) is a slash.
+ *
+ * Returns: true (1) if character is a slash, otherwise false (0).
+ */
 static bool path_char_is_slash(char c)
 {
 #ifdef _WIN32
@@ -91,6 +118,13 @@ static bool path_char_is_slash(char c)
 #endif
 }
 
+/**
+ * path_default_slash:
+ *
+ * Gets the default slash separator.
+ *
+ * Returns: default slash separator.
+ */
 static const char *path_default_slash(void)
 {
 #ifdef _WIN32
@@ -100,15 +134,33 @@ static const char *path_default_slash(void)
 #endif
 }
 
+/**
+ * path_contains_compressed_file:
+ * @path               : path
+ *
+ * Checks if path contains a compressed file.
+ *
+ * Currently we only check for hash symbol (#) inside the pathname.
+ * If path is ever expanded to a general URI, we should check for that here.
+ *
+ * Example:  Somewhere in the path there might be a compressed file
+ * E.g.: /path/to/file.7z#mygame.img
+ *
+ * Returns: true (1) if path contains compressed file, otherwise false (0).
+ **/
 bool path_contains_compressed_file(const char *path)
 {
-   /*
-    * Currently we only check for hash symbol inside the pathname.
-    * If path is ever expanded to a general URI, we should check for that here.
-    */
    return (strchr(path,'#') != NULL);
 }
 
+/**
+ * path_is_compressed_file:
+ * @path               : path
+ *
+ * Checks if path is a compressed file.
+ *
+ * Returns: true (1) if path is a compressed file, otherwise false (0).
+ **/
 bool path_is_compressed_file(const char* path)
 {
 #ifdef HAVE_COMPRESSION
@@ -126,6 +178,14 @@ bool path_is_compressed_file(const char* path)
    return false;
 }
 
+/**
+ * path_is_directory:
+ * @path               : path
+ *
+ * Checks if path is a directory.
+ *
+ * Returns: true (1) if path is a directory, otherwise false (0).
+ */
 bool path_is_directory(const char *path)
 {
 #ifdef _WIN32
@@ -140,6 +200,14 @@ bool path_is_directory(const char *path)
 #endif
 }
 
+/**
+ * path_file_exists:
+ * @path               : path
+ *
+ * Checks if a file already exists at the specified path (@path).
+ *
+ * Returns: true (1) if file already exists, otherwise false (0).
+ */
 bool path_file_exists(const char *path)
 {
    FILE *dummy = fopen(path, "rb");
@@ -151,6 +219,27 @@ bool path_file_exists(const char *path)
    return true;
 }
 
+/**
+ * fill_pathname:
+ * @out_path           : output path
+ * @in_path            : input  path
+ * @replace            : what to replace 
+ * @size               : buffer size of output path
+ *
+ * FIXME: Verify
+ *
+ * Replaces filename extension with 'replace' and outputs result to out_path.
+ * The extension here is considered to be the string from the last '.'
+ * to the end.
+ *
+ * Only '.'s after the last slash are considered as extensions.
+ * If no '.' is present, in_path and replace will simply be concatenated.
+ * 'size' is buffer size of 'out_path'.
+ * E.g.: in_path = "/foo/bar/baz/boo.c", replace = ".asm" => 
+ * out_path = "/foo/bar/baz/boo.asm" 
+ * E.g.: in_path = "/foo/bar/baz/boo.c", replace = ""     =>
+ * out_path = "/foo/bar/baz/boo" 
+ */
 void fill_pathname(char *out_path, const char *in_path,
       const char *replace, size_t size)
 {
@@ -166,6 +255,20 @@ void fill_pathname(char *out_path, const char *in_path,
    rarch_assert(strlcat(out_path, replace, size) < size);
 }
 
+/**
+ * fill_pathname_noext:
+ * @out_path           : output path
+ * @in_path            : input  path
+ * @replace            : what to replace 
+ * @size               : buffer size of output path
+ *
+ * Appends a filename extension 'replace' to 'in_path', and outputs
+ * result in 'out_path'.
+ *
+ * Assumes in_path has no extension. If an extension is still
+ * present in 'in_path', it will be ignored.
+ *
+ */
 void fill_pathname_noext(char *out_path, const char *in_path,
       const char *replace, size_t size)
 {
@@ -186,14 +289,20 @@ static char *find_last_slash(const char *str)
    return (char*)slash;
 }
 
-/* Assumes path is a directory. Appends a slash
+/** 
- * if not already there. */
+ * fill_pathname_slash:
+ * @path               : path
+ * @size               : size of path
+ *
+ * Assumes path is a directory. Appends a slash
+ * if not already there.
+ **/
 void fill_pathname_slash(char *path, size_t size)
 {
    size_t path_len = strlen(path);
    const char *last_slash = find_last_slash(path);
 
-   // Try to preserve slash type.
+   /* Try to preserve slash type. */
    if (last_slash && (last_slash != (path + path_len - 1)))
    {
       char join_str[2] = {*last_slash};
@@ -203,6 +312,23 @@ void fill_pathname_slash(char *path, size_t size)
       rarch_assert(strlcat(path, path_default_slash(), size) < size);
 }
 
+/**
+ * fill_pathname_dir:
+ * @in_dir             : input directory path
+ * @in_basename        : input basename to be appended to @in_dir
+ * @replace            : replacement to be appended to @in_basename
+ * @size               : size of buffer
+ *
+ * Appends basename of 'in_basename', to 'in_dir', along with 'replace'.
+ * Basename of in_basename is the string after the last '/' or '\\',
+ * i.e the filename without directories.
+ *
+ * If in_basename has no '/' or '\\', the whole 'in_basename' will be used.
+ * 'size' is buffer size of 'in_dir'.
+ *
+ * E.g..: in_dir = "/tmp/some_dir", in_basename = "/some_content/foo.c",
+ * replace = ".asm" => in_dir = "/tmp/some_dir/foo.c.asm"
+ **/
 void fill_pathname_dir(char *in_dir, const char *in_basename,
       const char *replace, size_t size)
 {
@@ -213,6 +339,14 @@ void fill_pathname_dir(char *in_dir, const char *in_basename,
    rarch_assert(strlcat(in_dir, replace, size) < size);
 }
 
+/**
+ * fill_pathname_base:
+ * @out                : output path         
+ * @in_path            : input path
+ * @size               : size of output path
+ *
+ * Copies basename of @in_path into @out_path.
+ **/
 void fill_pathname_base(char *out, const char *in_path, size_t size)
 {
    const char *ptr = find_last_slash(in_path);
@@ -241,6 +375,16 @@ void fill_pathname_base(char *out, const char *in_path, size_t size)
    rarch_assert(strlcpy(out, ptr, size) < size);
 }
 
+/**
+ * fill_pathname_basedir:
+ * @out_dir            : output directory        
+ * @in_path            : input path
+ * @size               : size of output directory
+ *
+ * Copies base directory of @in_path into @out_path.
+ * If in_path is a path without any slashes (relative current directory),
+ * @out_path will get path "./".
+ **/
 void fill_pathname_basedir(char *out_dir,
       const char *in_path, size_t size)
 {
@@ -248,6 +392,15 @@ void fill_pathname_basedir(char *out_dir,
    path_basedir(out_dir);
 }
 
+/**
+ * fill_pathname_parent_dir:
+ * @out_dir            : output directory        
+ * @in_dir             : input directory
+ * @size               : size of output directory
+ *
+ * Copies parent directory of @in_dir into @out_dir.
+ * Assumes @in_dir is a directory. Keeps trailing '/'.
+ **/
 void fill_pathname_parent_dir(char *out_dir,
       const char *in_dir, size_t size)
 {
@@ -255,6 +408,18 @@ void fill_pathname_parent_dir(char *out_dir,
    path_parent_dir(out_dir);
 }
 
+/**
+ * fill_dated_filename:
+ * @out_filename       : output filename
+ * @ext                : extension of output filename
+ * @size               : buffer size of output filename
+ *
+ * Creates a 'dated' filename prefixed by 'RetroArch', and 
+ * concatenates extension (@ext) to it.
+ *
+ * E.g.: 
+ * out_filename = "RetroArch-{month}{day}-{Hours}{Minutes}.{@ext}"
+ **/
 void fill_dated_filename(char *out_filename,
       const char *ext, size_t size)
 {
@@ -266,6 +431,13 @@ void fill_dated_filename(char *out_filename,
    strlcat(out_filename, ext, size);
 }
 
+/**
+ * path_basedir:
+ * @path               : path           
+ *
+ * Extracts base directory by mutating path.
+ * Keeps trailing '/'.
+ **/
 void path_basedir(char *path)
 {
    char *last = NULL;
@@ -287,6 +459,13 @@ void path_basedir(char *path)
       snprintf(path, 3, ".%s", path_default_slash());
 }
 
+/**
+ * path_parent_dir:
+ * @path               : path
+ *
+ * Extracts parent directory by mutating path.
+ * Assumes that path is a directory. Keeps trailing '/'.
+ **/
 void path_parent_dir(char *path)
 {
    size_t len = strlen(path);
@@ -295,12 +474,20 @@ void path_parent_dir(char *path)
    path_basedir(path);
 }
 
+/**
+ * path_basename:
+ * @path               : path
+ *
+ * Get basename from @path.
+ *
+ * Returns: basename from path.
+ **/
 const char *path_basename(const char *path)
 {
    const char *last = find_last_slash(path);
 
-   /* We cut either at the last hash or the last slash; whichever comes last */
 #ifdef HAVE_COMPRESSION
+   /* We cut either at the last hash or the last slash; whichever comes last */
    const char *last_hash = strchr(path,'#');
    if (last_hash > last)
       return last_hash + 1;
@@ -311,6 +498,14 @@ const char *path_basename(const char *path)
    return path;
 }
 
+/**
+ * path_is_absolute:
+ * @path               : path
+ *
+ * Checks if @path is an absolute path or a relative path.
+ *
+ * Returns: true (1) if path is absolute, false (1) if path is relative.
+ **/
 bool path_is_absolute(const char *path)
 {
 #ifdef _WIN32
@@ -322,6 +517,14 @@ bool path_is_absolute(const char *path)
 #endif
 }
 
+/**
+ * path_resolve_realpath:
+ * @buf                : buffer for path
+ * @size               : size of buffer
+ *
+ * Turns relative paths into absolute path.
+ * If relative, rebases on current working dir.
+ **/
 void path_resolve_realpath(char *buf, size_t size)
 {
 #ifndef RARCH_CONSOLE
@@ -348,6 +551,14 @@ void path_resolve_realpath(char *buf, size_t size)
 #endif
 }
 
+/**
+ * path_mkdir_norecurse:
+ * @dir                : directory
+ *
+ * Create directory on filesystem.
+ *
+ * Returns: true (1) if directory could be created, otherwise false (0).
+ **/
 static bool path_mkdir_norecurse(const char *dir)
 {
    int ret;
@@ -366,6 +577,14 @@ static bool path_mkdir_norecurse(const char *dir)
    return ret == 0;
 }
 
+/**
+ * path_mkdir:
+ * @dir                : directory
+ *
+ * Create directory on filesystem.
+ *
+ * Returns: true (1) if directory could be created, otherwise false (0).
+ **/
 bool path_mkdir(const char *dir)
 {
    const char *target = NULL;
@@ -406,6 +625,18 @@ end:
    return ret;
 }
 
+/**
+ * fill_pathname_resolve_relative:
+ * @out_path           : output path
+ * @in_refpath         : input reference path
+ * @in_path            : input path
+ * @size               : size of @out_path
+ *
+ * Joins basedir of @in_refpath together with @in_path.
+ * If @in_path is an absolute path, out_path = in_path.
+ * E.g.: in_refpath = "/foo/bar/baz.a", in_path = "foobar.cg",
+ * out_path = "/foo/bar/foobar.cg".
+ **/
 void fill_pathname_resolve_relative(char *out_path,
       const char *in_refpath, const char *in_path, size_t size)
 {
@@ -419,6 +650,17 @@ void fill_pathname_resolve_relative(char *out_path,
    }
 }
 
+/**
+ * fill_pathname_join:
+ * @out_path           : output path
+ * @dir                : directory   
+ * @path               : path
+ * @size               : size of output path
+ *
+ * Joins a directory (@dir) and path (@path) together.
+ * Makes sure not to get  two consecutive slashes 
+ * between directory and path.
+ **/
 void fill_pathname_join(char *out_path,
       const char *dir, const char *path, size_t size)
 {
@@ -430,6 +672,17 @@ void fill_pathname_join(char *out_path,
    rarch_assert(strlcat(out_path, path, size) < size);
 }
 
+/**
+ * fill_pathname_join_delim:
+ * @out_path           : output path
+ * @dir                : directory   
+ * @path               : path
+ * @delim              : delimiter 
+ * @size               : size of output path
+ *
+ * Joins a directory (@dir) and path (@path) together 
+ * using the given delimiter (@delim).
+ **/
 void fill_pathname_join_delim(char *out_path, const char *dir,
       const char *path, const char delim, size_t size)
 {
@@ -483,6 +736,21 @@ void fill_pathname_expand_special(char *out_path,
    rarch_assert(strlcpy(out_path, in_path, size) < size);
 }
 
+/**
+ * fill_short_pathname_representation:
+ * @out_rep            : output representation
+ * @in_path            : input path
+ * @size               : size of output representation
+ *
+ * Generates a short representation of path. It should only
+ * be used for displaying the result; the output representation is not
+ * binding in any meaningful way (for a normal path, this is the same as basename)
+ * In case of more complex URLs, this should cut everything except for
+ * the main image file.
+ *
+ * E.g.: "/path/to/game.img" -> game.img
+ *       "/path/to/myarchive.7z#folder/to/game.img" -> game.img
+ */
 void fill_short_pathname_representation(char* out_rep,
       const char *in_path, size_t size)
 {
@@ -507,7 +775,6 @@ void fill_short_pathname_representation(char* out_rep,
       strlcpy(out_rep,path_short, size);
 }
 
-
 void fill_pathname_abbreviate_special(char *out_path,
       const char *in_path, size_t size)
 {

libretro-sdk/include/file/file_path.h

@@ -47,47 +47,141 @@ enum
 };
 
 
-/* path_is_compressed_file also means: The compressed file is supported */
+/**
+ * path_is_compressed_file:
+ * @path               : path
+ *
+ * Checks if path is a compressed file.
+ *
+ * Returns: true (1) if path is a compressed file, otherwise false (0).
+ **/
 bool path_is_compressed_file(const char *path);
 
-/* Somewhere in the path there might be a compressed file
+/**
+ * path_contains_compressed_file:
+ * @path               : path
+ *
+ * Checks if path contains a compressed file.
+ *
+ * Currently we only check for hash symbol (#) inside the pathname.
+ * If path is ever expanded to a general URI, we should check for that here.
+ *
+ * Example:  Somewhere in the path there might be a compressed file
  * E.g.: /path/to/file.7z#mygame.img
- */
+ *
+ * Returns: true (1) if path contains compressed file, otherwise false (0).
+ **/
 bool path_contains_compressed_file(const char *path);
 
+/**
+ * path_is_directory:
+ * @path               : path
+ *
+ * Checks if path is a directory.
+ *
+ * Returns: true (1) if path is a directory, otherwise false (0).
+ */
 bool path_is_directory(const char *path);
 
+/**
+ * path_file_exists:
+ * @path               : path
+ *
+ * Checks if a file already exists at the specified path (@path).
+ *
+ * Returns: true (1) if file already exists, otherwise false (0).
+ */
 bool path_file_exists(const char *path);
 
-/* Gets extension of file. Only '.'s after the last slash are considered. */
+/**
+ * path_get_extension:
+ * @path               : path
+ *
+ * Gets extension of file. Only '.'s 
+ * after the last slash are considered.
+ *
+ * Returns: extension part from the path.
+ */
 const char *path_get_extension(const char *path);
 
+/**
+ * path_mkdir:
+ * @dir                : directory
+ *
+ * Create directory on filesystem.
+ *
+ * Returns: true (1) if directory could be created, otherwise false (0).
+ **/
 bool path_mkdir(const char *dir);
 
-/* Removes all text after and including the last '.'.
+/**
- * Only '.'s after the last slash are considered. */
+ * path_remove_extension:
+ * @path               : path
+ *
+ * Removes the extension from the path and returns the result.
+ * Removes all text after and including the last '.'.
+ * Only '.'s after the last slash are considered.
+ *
+ * Returns: path with the extension part removed.
+ */
 char *path_remove_extension(char *path);
 
-/* Returns basename from path. */
+/**
+ * path_basename:
+ * @path               : path
+ *
+ * Get basename from @path.
+ *
+ * Returns: basename from path.
+ **/
 const char *path_basename(const char *path);
 
-/* Extracts base directory by mutating path.
+/**
- * Keeps trailing '/'. */
+ * path_basedir:
+ * @path               : path           
+ *
+ * Extracts base directory by mutating path.
+ * Keeps trailing '/'.
+ **/
 void path_basedir(char *path);
 
-/* Extracts parent directory by mutating path.
+/**
- * Assumes that path is a directory. Keeps trailing '/'. */
+ * path_parent_dir:
+ * @path               : path
+ *
+ * Extracts parent directory by mutating path.
+ * Assumes that path is a directory. Keeps trailing '/'.
+ **/
 void path_parent_dir(char *path);
 
-/* Turns relative paths into absolute path.
+/**
- * If relative, rebases on current working dir. */
+ * path_resolve_realpath:
+ * @buf                : buffer for path
+ * @size               : size of buffer
+ *
+ * Turns relative paths into absolute path.
+ * If relative, rebases on current working dir.
+ **/
 void path_resolve_realpath(char *buf, size_t size);
 
+/**
+ * path_is_absolute:
+ * @path               : path
+ *
+ * Checks if @path is an absolute path or a relative path.
+ *
+ * Returns: true (1) if path is absolute, false (1) if path is relative.
+ **/
 bool path_is_absolute(const char *path);
 
-/* Path-name operations.
+/**
- * If any of these operation are detected to overflow, the application will 
+ * fill_pathname:
- * be terminated.
+ * @out_path           : output path
+ * @in_path            : input  path
+ * @replace            : what to replace 
+ * @size               : buffer size of output path
+ *
+ * FIXME: Verify
  *
  * Replaces filename extension with 'replace' and outputs result to out_path.
  * The extension here is considered to be the string from the last '.'
@@ -104,20 +198,46 @@ bool path_is_absolute(const char *path);
 void fill_pathname(char *out_path, const char *in_path,
       const char *replace, size_t size);
 
+/**
+ * fill_dated_filename:
+ * @out_filename       : output filename
+ * @ext                : extension of output filename
+ * @size               : buffer size of output filename
+ *
+ * Creates a 'dated' filename prefixed by 'RetroArch', and 
+ * concatenates extension (@ext) to it.
+ *
+ * E.g.: 
+ * out_filename = "RetroArch-{month}{day}-{Hours}{Minutes}.{@ext}"
+ **/
 void fill_dated_filename(char *out_filename,
       const char *ext, size_t size);
 
-/* Appends a filename extension 'replace' to 'in_path', and outputs
+/**
+ * fill_pathname_noext:
+ * @out_path           : output path
+ * @in_path            : input  path
+ * @replace            : what to replace 
+ * @size               : buffer size of output path
+ *
+ * Appends a filename extension 'replace' to 'in_path', and outputs
  * result in 'out_path'.
  *
  * Assumes in_path has no extension. If an extension is still
  * present in 'in_path', it will be ignored.
  *
- * 'size' is buffer size of 'out_path'. */
+ */
 void fill_pathname_noext(char *out_path, const char *in_path,
       const char *replace, size_t size);
 
-/* Appends basename of 'in_basename', to 'in_dir', along with 'replace'.
+/**
+ * fill_pathname_dir:
+ * @in_dir             : input directory path
+ * @in_basename        : input basename to be appended to @in_dir
+ * @replace            : replacement to be appended to @in_basename
+ * @size               : size of buffer
+ *
+ * Appends basename of 'in_basename', to 'in_dir', along with 'replace'.
  * Basename of in_basename is the string after the last '/' or '\\',
  * i.e the filename without directories.
  *
@@ -126,45 +246,99 @@ void fill_pathname_noext(char *out_path, const char *in_path,
  *
  * E.g..: in_dir = "/tmp/some_dir", in_basename = "/some_content/foo.c",
  * replace = ".asm" => in_dir = "/tmp/some_dir/foo.c.asm"
- *
+ **/
- * */
 void fill_pathname_dir(char *in_dir, const char *in_basename,
       const char *replace, size_t size);
 
-/* Copies basename of in_path into out_path. */
+/**
+ * fill_pathname_base:
+ * @out                : output path         
+ * @in_path            : input path
+ * @size               : size of output path
+ *
+ * Copies basename of @in_path into @out_path.
+ **/
 void fill_pathname_base(char *out_path, const char *in_path, size_t size);
 
-/* Copies base directory of in_path into out_path.
+/**
+ * fill_pathname_basedir:
+ * @out_dir            : output directory        
+ * @in_path            : input path
+ * @size               : size of output directory
+ *
+ * Copies base directory of @in_path into @out_path.
  * If in_path is a path without any slashes (relative current directory),
- * out_path will get path "./". */
+ * @out_path will get path "./".
+ **/
 void fill_pathname_basedir(char *out_path, const char *in_path, size_t size);
 
-/* Copies parent directory of in_dir into out_dir.
+/**
- * Assumes in_dir is a directory. Keeps trailing '/'. */
+ * fill_pathname_parent_dir:
+ * @out_dir            : output directory        
+ * @in_dir             : input directory
+ * @size               : size of output directory
+ *
+ * Copies parent directory of @in_dir into @out_dir.
+ * Assumes @in_dir is a directory. Keeps trailing '/'.
+ **/
 void fill_pathname_parent_dir(char *out_dir,
       const char *in_dir, size_t size);
 
-/* Joins basedir of in_refpath together with in_path.
+/**
- * If in_path is an absolute path, out_path = in_path.
+ * fill_pathname_resolve_relative:
+ * @out_path           : output path
+ * @in_refpath         : input reference path
+ * @in_path            : input path
+ * @size               : size of @out_path
+ *
+ * Joins basedir of @in_refpath together with @in_path.
+ * If @in_path is an absolute path, out_path = in_path.
  * E.g.: in_refpath = "/foo/bar/baz.a", in_path = "foobar.cg",
- * out_path = "/foo/bar/foobar.cg". */
+ * out_path = "/foo/bar/foobar.cg".
+ **/
 void fill_pathname_resolve_relative(char *out_path, const char *in_refpath,
       const char *in_path, size_t size);
 
-/* Joins a directory and path together. Makes sure not to get 
+/**
- * two consecutive slashes between dir and path. */
+ * fill_pathname_join:
+ * @out_path           : output path
+ * @dir                : directory   
+ * @path               : path
+ * @size               : size of output path
+ *
+ * Joins a directory (@dir) and path (@path) together.
+ * Makes sure not to get  two consecutive slashes 
+ * between directory and path.
+ **/
 void fill_pathname_join(char *out_path, const char *dir,
       const char *path, size_t size);
 
-/* Joins a directory and path together using the given char. */
+/**
+ * fill_pathname_join_delim:
+ * @out_path           : output path
+ * @dir                : directory   
+ * @path               : path
+ * @delim              : delimiter 
+ * @size               : size of output path
+ *
+ * Joins a directory (@dir) and path (@path) together 
+ * using the given delimiter (@delim).
+ **/
 void fill_pathname_join_delim(char *out_path, const char *dir,
       const char *path, const char delim, size_t size);
 
-/* Generates a short representation of path. It should only
+/**
+ * fill_short_pathname_representation:
+ * @out_rep            : output representation
+ * @in_path            : input path
+ * @size               : size of output representation
+ *
+ * Generates a short representation of path. It should only
  * be used for displaying the result; the output representation is not
  * binding in any meaningful way (for a normal path, this is the same as basename)
  * In case of more complex URLs, this should cut everything except for
  * the main image file.
+ *
  * E.g.: "/path/to/game.img" -> game.img
  *       "/path/to/myarchive.7z#folder/to/game.img" -> game.img
  */
@@ -177,6 +351,14 @@ void fill_pathname_expand_special(char *out_path,
 void fill_pathname_abbreviate_special(char *out_path,
       const char *in_path, size_t size);
 
+/** 
+ * fill_pathname_slash:
+ * @path               : path
+ * @size               : size of path
+ *
+ * Assumes path is a directory. Appends a slash
+ * if not already there.
+ **/
 void fill_pathname_slash(char *path, size_t size);
 
 #ifndef RARCH_CONSOLE