From d4dc802f31b124fffaaa99366abcb14b9d07f074 Mon Sep 17 00:00:00 2001
From: twinaphex <libretro@gmail.com>
Date: Fri, 16 Jan 2015 02:01:05 +0100
Subject: [PATCH] Document file_ops.h

---
 content.c  | 12 ++++++------
 file_ops.h | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/content.c b/content.c
index 202d16dcbf..a5c61ca8e5 100644
--- a/content.c
+++ b/content.c
@@ -403,15 +403,15 @@ void save_ram_file(const char *path, int type)
    if (size <= 0)
       return;
 
-   if (write_file(path, data, size))
+   if (!write_file(path, data, size))
    {
-      RARCH_LOG("Saved successfully to \"%s\".\n", path);
+      RARCH_ERR("Failed to save SRAM.\n");
+      RARCH_WARN("Attempting to recover ...\n");
+      dump_to_file_desperate(data, size, type);
       return;
    }
 
-   RARCH_ERR("Failed to save SRAM.\n");
-   RARCH_WARN("Attempting to recover ...\n");
-   dump_to_file_desperate(data, size, type);
+   RARCH_LOG("Saved successfully to \"%s\".\n", path);
 }
 
 /**
@@ -642,7 +642,7 @@ bool init_content_file(void)
       if (content->elems[i].attr.i & 1)
          continue;
 
-      ext = path_get_extension(content->elems[i].data);
+      ext       = path_get_extension(content->elems[i].data);
       valid_ext = special ? special->roms[i].valid_extensions :
          g_extern.system.info.valid_extensions;
 
diff --git a/file_ops.h b/file_ops.h
index e84c5fdb5c..df51dec9a0 100644
--- a/file_ops.h
+++ b/file_ops.h
@@ -29,14 +29,49 @@ extern "C" {
 #endif
 
 #ifdef HAVE_COMPRESSION
+/* Generic compressed file loader.
+ * Extracts to buf, unless optional_filename != 0
+ * Then extracts to optional_filename and leaves buf alone.
+ */
 long read_compressed_file(const char * path, void **buf,
       const char* optional_filename);
 #endif
 
+/**
+ * read_file:
+ * @path             : path to file.
+ * @buf              : buffer to allocate and read the contents of the
+ *                     file into. Needs to be freed manually.
+ *
+ * Read the contents of a file into @buf. Will call read_compressed_file
+ * if path contains a compressed file, otherwise will call read_generic_file.
+ *
+ * Returns: number of items read, -1 on error.
+ */
 long read_file(const char *path, void **buf);
 
+/**
+ * read_file_string:
+ * @path             : path to file to be read from.
+ * @buf              : buffer to allocate and read the contents of the
+ *                     file into. Needs to be freed manually.
+ *
+ * Reads file content as one string.
+ *
+ * Returns: true (1) on success, false (0) otherwise.
+ */
 bool read_file_string(const char *path, char **buf);
 
+/**
+ * write_file:
+ * @path             : path to file.
+ * @data             : contents to write to the file.
+ * @size             : size of the contents.
+ *
+ * Writes data to a file.
+ *
+ * Returns: true (1) on success, false (0) otherwise.
+ */
 bool write_file(const char *path, const void *buf, size_t size);
 
 #ifdef __cplusplus