[Add] Documented pack.*

src/pack.c

@@ -9,7 +9,11 @@
 #include "log.h"
 #include "md5.h"
 
-/* == Store data in a funky format. =======================
+/*
+ * @file pack.c
+ *
+ * @brief Stores data in funky format.
+ *
  * Format:
  *  -- Index.
  *    -- Magic number (16 bytes).
@@ -26,23 +30,27 @@
  * -- Write magic number and number of files.
  * -- Write the index.
  * -- Pack the files.
- * ========================================================
  */
 
-#undef DEBUG /* this will be spammy. */
+#undef DEBUG /* This will be spammy. */
 #define DEBUG(str, args...) do{;} while(0)
 
-/* The read/write block size. */
+#define BLOCKSIZE 128*1024 /**< The read/write block size */
-#define BLOCKSIZE 128*1024
 
 /* Max filename length. */
-#define MAX_FILENAME 100
+#define MAX_FILENAME 100 /**< Maximum file name length. */
 
-#define PERMS S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH
+#define PERMS S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH /**< Default permissions. */
 
-const uint64_t magic = 0x25524573; /* sER% */
+const uint64_t magic = 0x25524573; /**< File magic number: sER% */
 
-/* Grab the filesize. */
+/**
+ * @fn static off_t getfilesize(const char* filename)
+ *
+ * @brief Get the file size.
+ *    @param filename File to get the size of.
+ *    @return The size of the file.
+ */
 static off_t getfilesize(const char* filename) {
 #ifdef _POSIX_SOURCE
   struct stat file;
@@ -66,7 +74,13 @@ static off_t getfilesize(const char* filename) {
 #endif
 }
 
-/* Return true if filename is a Packfile. */
+/**
+ * @fn int pack_check(const char* filename)
+ *
+ * @brief Check to see if a file is a packfile
+ *    @param filename Name of the file to check.
+ *    @return 1 if it is a packfile, 0 if it isn't and -1 on error.
+ */
 int pack_check(const char* filename) {
   int ret;
   char* buf;
@@ -109,7 +123,15 @@ int pack_check(const char* filename) {
   return ret;
 }
 
-/* Pack nfiles, infiles into outfile. */
+/**
+ * @fn int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles)
+ *
+ * @brief Packages files into a packfile.
+ *    @param outfile Name of the file to output to.
+ *    @param infiles Array of filenames to package.
+ *    @param nfiles Number of filenames in infiles.
+ *    @return 0 on success.
+ */
 #ifdef _POSIX_SOURCE
 #define WRITE(b,n) if(write(outfd, b, n)==-1) { \
   ERR("Error writing to file: %s", strerror(errno)); \
@@ -229,7 +251,15 @@ int pack_files(const char* outfile, const char** infiles, const uint32_t nfiles)
 }
 #undef WRITE
 
-/* Opens the filename in packfile for reading. */
+/**
+ * @fn int pack_open(Packfile* file, const char* packfile, const char* filename)
+ *
+ * @brief Open a file in the packfile for reading.
+ *    @param file Packfile to store data into.
+ *    @param packfile Path to real packfile.
+ *    @param filename Name of the file within th. packfile.
+ *    @return 0 on success.
+ */
 #ifdef _POSIX_SOURCE
 #define READ(b,n) if(read(file->fd, (b), (n))!=(n)) { \
   ERR("Too few bytes read. Expected more."); \
@@ -308,7 +338,17 @@ int pack_open(Packfile* file, const char* packfile, const char* filename) {
 }
 #undef READ
 
-/* Read count bytes from file and put them into buf. */
+/**
+ * @fn ssize_t pack_read(Packfile* file, void* buf, size_t count)
+ *
+ * @brief Reads data from a packfile.
+ *
+ * Behaves like POSIX read.
+ *    @param file Opened packfile to read data from.
+ *    @param buf Allocated buffer to read into.
+ *    @param count Bytes to read.
+ *    @return Bytes to read or -1 on error.
+ */
 ssize_t pack_read(Packfile* file, void* buf, size_t count) {
   if(file->pos + count > file->end)
     count = file->end - file->pos; /* Can't go past the end! */
@@ -329,7 +369,19 @@ ssize_t pack_read(Packfile* file, void* buf, size_t count) {
   return bytes;
 }
 
-/* Seek in the packfile. */
+/**
+ * @fn off_t pack_seek(Packfile* file, off_t offset, int whence)
+ *
+ * @brief Seeks within a file inside a packfile.
+ *
+ * Behaves like lseek/fseek.
+ *
+ * @todo It's broken, needs fixing.
+ *    @param file File to seek.
+ *    @param offset Position to seek to.
+ *    @param whence Either SEEK_SET, SEEK_CUR or SEEK_END.
+ *    @return The position moved to.
+ */
 off_t pack_seek(Packfile* file, off_t offset, int whence) {
   DEBUG("Attempting to seek offset: %d, whence: %d", offset, whence);
   off_t ret;
@@ -374,12 +426,26 @@ off_t pack_seek(Packfile* file, off_t offset, int whence) {
   return ret - file->start;
 }
 
-/* Return current pointer position. */
+/**
+ * @fn long pack_tell(Packfile* file)
+ *
+ * @brief Get the current position in the file.
+ *    @param file Packfile to get the position from.
+ *    @return The current position in the file.
+ */
 long pack_tell(Packfile* file) {
   return file->pos - file->start;
 }
 
-/* Loads an entire file into memory and returns a pointer to it. */
+/**
+ * @fn void* pack_readfile(const char* packfile, const char* filename, uint32_t* filesize)
+ *
+ * @brief Read an entire file into memory.
+ *    @param packfile Name of the packfile to read from.
+ *    @param filename Name of the packed file to read.
+ *    @param filesize Is set to the size of the file.
+ *    @return A pointer to the sata in the file or NULL if an error accured.
+ */
 void* pack_readfile(const char* packfile, const char* filename, uint32_t* filesize) {
   Packfile* file = (Packfile*)malloc(sizeof(Packfile));
   void* buf;
@@ -446,9 +512,16 @@ void* pack_readfile(const char* packfile, const char* filename, uint32_t* filesi
   return buf;
 }
 
-/* Load the filenames int the packfile to filenames. */
+/**
-/* filenames should be freed after use */
+ * @fn char** pack_listfiles(const char* packfile, uint32_t* nfiles)
-/* On error if filenames is (char**)-1. */
+ *
+ * @brief Get what files are in the packfile.
+ *
+ * Each name must be freed individually afterwords and the array of names too.
+ *    @param packfile Packfile to query it's internal files.
+ *    @param nfiles Stores the amount of files in packfile.
+ *    @return An array of filenames in packfile.
+ */
 #ifdef _POSIX_SOURCE
 #define READ(b,n) if(read(fd, (b), (n))!=(n)) { \
   ERR("Too few bytes read"); \
@@ -510,7 +583,13 @@ char** pack_listfiles(const char* packfile, uint32_t* nfiles) {
 }
 #undef READ
 
-/* Close the packfile. */
+/**
+ * @fn int pack_close(Packfile* file)
+ *
+ * @brief Closes a packfile.
+ *    @param file Packfile to close.
+ *    @return 0 on success.
+ */
 int pack_close(Packfile* file) {
   int i;
 #ifdef _POSIX_SOURCE

src/pack.h

@@ -5,14 +5,21 @@
 #endif
 #include <stdint.h>
 
+
+/**
+ * @struct Packfile
+ *
+ * @brief Abstracts around packfile
+ */
 typedef struct Packfile_ {
 #ifdef _POSIX_SOURCE
-  int fd; /* File descriptor. */
+  int fd;               /**< File descriptor. */
 #else
-  FILE* fp;
+  FILE* fp;             /**< For non-posix. */
 #endif
-  uint32_t pos; /* position. */
+  uint32_t pos;         /**< position. */
-  uint32_t start, end; /* file limits. */
+  uint32_t start;       /**< File start */
+  uint32_t end;         /**< File end. */
 } Packfile;
 
 /* Packfile manipulation. Automatically allocated and freed (with open and close). */