[Add] Documentation for lfile.c

dat/faction.xml

@@ -29,7 +29,7 @@
   </enemies>
  </faction>
  <faction name="Pirate">
-   <longname>Gallactic Pirates</longname>
+   <longname>Galactic Pirates</longname>
   <player>-20</player>
   <enemies>
    <enemy>Empire</enemy>

src/lfile.c

@@ -1,3 +1,9 @@
+/**
+ * @file lfile.c
+ *
+ * @brief Handle read/write abstractions to the users directory.
+ */
+
 #include <string.h>
 #include <stdarg.h>
 #ifdef LINUX
@@ -14,8 +20,13 @@
 #include "log.h"
 #include "lfile.h"
 
-/* Return lephisto's base path. */
-static char lephisto_base[128] = "\0";
+/**
+ * @fn char* lfile_basePath(void)
+ *
+ * @brief Get Lephisto's base path (for saves etc..).
+ *    @return The base path to Lephisto.
+ */
+static char lephisto_base[128] = "\0"; /**< Store Lephisto's base path. */
 char* lfile_basePath(void) {
   char* home;
 
@@ -31,8 +42,15 @@ char* lfile_basePath(void) {
   return lephisto_base;
 }
 
-/* Check if a directory exists, and create it if it doesn't. */
-/* Based on lephisto_base. */
+/**
+ * @fn int lfile_dirMakeExist(const char* path)
+ *
+ * @brief Create a directory if it doesn't exist.
+ *
+ * Uses relative path to basePath.
+ *    @param path Path to create directory if it doesn't exist.
+ *    @return 0 on success.
+ */
 int lfile_dirMakeExist(const char* path) {
   char file[PATH_MAX];
 
@@ -58,7 +76,13 @@ int lfile_dirMakeExist(const char* path) {
   return 0;
 }
 
-/* Check if a file exists. */
+/**
+ * @fn int lfile_fileExists(const char* path, ...)
+ *
+ * @brief Check to see if a file exists.
+ *    @param path printf formatted string pointing to the file to check for existance.
+ *    @return 1 if file exists, 0 if it doesn't or -1 on error.
+ */
 int lfile_fileExists(const char* path, ...) {
   char file[PATH_MAX], name[PATH_MAX];
   va_list ap;
@@ -85,7 +109,16 @@ int lfile_fileExists(const char* path, ...) {
   return 0;
 }
 
-/* List all the files in a dir (besides . and ..). */
+/**
+ * @fn char** lfile_readDir(int* lfiles, const char* path)
+ *
+ * @brief Lists all the visible files in a directory.
+ *
+ * Should also sort by last modified but thats up to the OS in question.
+ * Paths are relative to base directory.
+ *    @param[out] lfiles Returns how many files there are.
+ *    @param path Directory to read.
+ */
 char** lfile_readDir(int* lfiles, const char* path) {
   char file[PATH_MAX];
   char** files;