headers: add docs

Author: myfreeer

pak_defs.h

@@ -39,6 +39,11 @@ typedef struct PakAlias {
 
 #pragma pack(pop)
 
+/**
+ * Get pak version from pak buffer.
+ * @param void *buffer - pointer to pak.
+ * @return uint32_t - pak version.
+ */
 #define pakGetVerison(buffer) (*(uint32_t *)buffer)
 #define PAK_HEADER_SIZE_V4 sizeof(PakHeaderV4)
 #define PAK_HEADER_SIZE_V5 sizeof(PakHeaderV5)

pak_file.h

@@ -8,9 +8,32 @@
 
 #include "pak_defs.h"
 #include "pak_header.h"
+
+/**
+ * Package a pak file, returns NULL_File on failure.
+ * Note: this would allocate memory.
+ * @param MyPakHeader *myHeader - pointer to MyPakHeader struct.
+ * @param PakFile *pakResFile - pointer to all resource files.
+ * @param PakAlias *pakAlias - pointer to all alias.
+ * @return PakFile - the packed file.
+ */
 PakFile pakPackFiles(MyPakHeader *myHeader, PakFile *pakResFile,
                      PakAlias *pakAlias);
+
+/**
+ * Get a single file from pak, returns NULL_File on failure.
+ * @param void *pakBuffer - pointer to pak.
+ * @param uint16_t *id - target file id.
+ * @return PakFile - the target file.
+ */
 PakFile pakGetFile(void *pakBuffer, uint16_t id);
+
+/**
+ * Get all files from pak, returns NULL on failure.
+ * Note: this would allocate memory.
+ * @param void* buffer - pointer to pak.
+ * @return PakFile* - pointer to all files in pak.
+ */
 PakFile *pakGetFiles(void *buffer);
 
 #endif // __PAK_FILE_H__

pak_file_io.h

@@ -7,7 +7,20 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/**
+ * Read a file into memory, returns NULL_File on failure.
+ * Note: this would allocate memory.
+ * @param const char *fileName - target file name.
+ * @return PakFile - target file content.
+ */
 PakFile readFile(const char *fileName);
+
+/**
+ * Write a file to storage, this would overwrite existing file.
+ * @param const char *fileName - target file name.
+ * @param PakFile file - target file content.
+ * @return bool - succeed or not.
+ */
 bool writeFile(const char *fileName, const PakFile file);
 
 #endif // __PAK_FILE_IO_H__

pak_get_file_type.h

@@ -13,9 +13,21 @@ typedef struct FileType {
     uint8_t size;
 } FileType;
 
+/**
+ * Generate a FileType, for internal uses only.
+ * @param char* type - file extension.
+ * @param char* identifer - file header identifer in string.
+ * @see pakGetFileType()
+ * @return FileType
+ */
 #define PAK_GEN_FILE_TYPE(type, identifer) \
     {type, identifer, sizeof(identifer) - 1}
 
+/**
+ * Get file extension form a file, returns "" on failure.
+ * @param PakFile file - the file to parse.
+ * @return char* - pointer to file extension.
+ */
 char *pakGetFileType(PakFile file);
 
 #endif // __PAK_GET_FILE_TYPE_H__

pak_header.h

@@ -5,8 +5,28 @@
 #include <stdio.h>
 #include <strings.h>
 
+/**
+ * Generate MyPakHeader struct from pak buffer.
+ * @param _in_ void *buffer - pointer to pak buffer.
+ * @param _out_ MyPakHeader myHeader - target file content.
+ * @return bool - succeed or not.
+ */
 bool pakParseHeader(void *buffer, MyPakHeader *myHeader);
+
+/**
+ * Write pak header from MyPakHeader struct to buffer.
+ * @param MyPakHeader myHeader - target MyPakHeader struct.
+ * @param void *buffer - pointer to target pak buffer.
+ * @return unsigned int - pak header size, 0 on failure.
+ */
 unsigned int pakWriteHeader(MyPakHeader *myHeader, void *buffer);
+
+/**
+ * Check if pak format is legal.
+ * @param void *buffer - pointer to pak buffer.
+ * @param unsigned int size - pak buffer size in bytes.
+ * @return bool - succeed or not.
+ */
 bool pakCheckFormat(void *buffer, unsigned int size);
 
 #endif // __PAK_HEADERS_H__

pak_pack.h

@@ -18,8 +18,32 @@
 #include "pak_file_io.h"
 #include "pak_get_file_type.h"
 #include "pak_header.h"
+
+/**
+ * Unpack a pak file to target path.
+ * @param void *buffer - pointer to target pak buffer.
+ * @param char *outputPath - target path.
+ * @return bool - succeed or not.
+ */
 bool pakUnpack(void *buffer, char *outputPath);
+
+/**
+ * Pack a pak file from target index (ini) file,
+ * returns NULL_File on failure.
+ * Note: this would allocate memory.
+ * @param PakFile pakIndex - target pak index file.
+ * @param char *path - target path.
+ * @return PakFile - packed pak.
+ */
 PakFile pakPack(PakFile pakIndex, char *path);
+
+/**
+ * Count number of specified char in string.
+ * @param char *string - target string.
+ * @param uint32_t length - target string length.
+ * @param char toCount - specified char to count.
+ * @return uint32_t - number of specified char.
+ */
 uint32_t countChar(char *string, uint32_t length, char toCount);
 
 #endif // __PAK_PACKER_UNPACKER_H__