New tests, documentation improvements

Makefile

@@ -106,20 +106,24 @@ clean:
 check: hTable.o regionParser.o chunkParser.o cNBT.o model.o
 	#hTable tests
 	checkmk tests/hTable.check > tests/hTableCheck.c
-	gcc tests/hTableCheck.c hTable.o -lcheck -lm $(SUBUNIT) -Wall -o tests/hTableCheck
+	gcc tests/hTableCheck.c hTable.o -lcheck -g -lm $(SUBUNIT) -Wall -o tests/hTableCheck
 	./tests/hTableCheck
 	#regionParser tests
 	checkmk tests/regionParser.check > tests/regionParserCheck.c
-	gcc tests/regionParserCheck.c regionParser.o -lcheck -lm $(ZLIB) $(SUBUNIT) -o tests/regionParserCheck
+	gcc tests/regionParserCheck.c regionParser.o -lcheck -g -lm $(ZLIB) $(SUBUNIT) -o tests/regionParserCheck
 	./tests/regionParserCheck
 	#chunkParser tests
 	checkmk tests/chunkParser.check > tests/chunkParserCheck.c
-	gcc tests/chunkParserCheck.c chunkParser.o cNBT.o -lcheck -lm $(SUBUNIT) -o tests/chunkParserCheck
+	gcc tests/chunkParserCheck.c chunkParser.o cNBT.o -lcheck -g -lm $(SUBUNIT) -o tests/chunkParserCheck
 	./tests/chunkParserCheck
 	#model tests
 	checkmk tests/model.check > tests/modelCheck.c
-	gcc tests/modelCheck.c model.o hTable.o -lcheck -lm $(SUBUNIT) -o tests/modelCheck
+	gcc tests/modelCheck.c model.o hTable.o -lcheck -g -lm $(SUBUNIT) -o tests/modelCheck
 	./tests/modelCheck
+	#wavefront tests
+	checkmk tests/wavefront.check > tests/wavefrontCheck.c
+	gcc tests/wavefrontCheck.c model.o hTable.o -lcheck -g -lm $(SUBUNIT) -o tests/wavefrontCheck
+	./tests/wavefrontCheck
 
 doc: src/lib/*.h src/*.c src/lib/*.c doc/Doxyfile.conf
 	doxygen ./doc/Doxyfile.conf

README.md

@@ -148,7 +148,7 @@ These are compiled automatically using make, and then linked together into cNBT.
 Most of the code has been organized into four "libraries".
 These may prove to be useful should you want to parse Minecraft save files or generate wavefront 3D models.
 Feel free to use these as libraries in your projects just make sure to read the license before you do so.
-The documentation for functions in these libraries should be mainly in header files and on [GitHub Pages](https://tca166.github.io/mcSavefileParsers/), and I will gladly expand it should there be a need so just let me know.
+The documentation for functions in these libraries should be mainly in header files and on GitHub Pages, and I will gladly expand it should there be a need so just let me know.
 
 - regionParser  
     This library provides three functions for parsing region files.

src/lib/chunkParser.h

@@ -15,14 +15,42 @@
 /*!
  @struct section
  @brief 16x16x16 section of a chunk
+ @details The section structure contains the block data, the block palette, the y coordinate of the section and the lengths of the block data and palette
+ @note This struct is mainly used for holding the raw nbt data of a section
+ @todo Add biomes
+ @see getBlockStates
  @ingroup chunkParser
 */
-typedef struct section{
+typedef struct{
     //we ignore the biomes because we don't need that data
-    uint64_t* blockData; //raw nbt file block data
+    /*! 
+     @var blockData
+     @brief raw nbt section block data
+     @details Packed array with padding, so that the individual block data isn't split.
+     @details The length of one element in this packed array is 4 or log2(paletteLen) whichever is higher.
+     @details the individual values stored here point to the identifiers in blockPalette
+     @warning can be NULL, in which case the section is full of the same block type: blockPalette[0]
+    */
+    uint64_t* blockData; 
+    /*!
+     @var blockPalette
+     @brief A string array of block identifiers
+    */
     char** blockPalette;
-    size_t blockDataLen; //the length of blockData in bytes
+    /*!
+     @var blockDataLen
+     @brief Length of the blockData long array
+    */
+    size_t blockDataLen;
+    /*!
+     @var paletteLen
+     @brief Length of the blockPalette array
+    */
     size_t paletteLen;
+    /*!
+     @var y
+     @brief the y index of this section. They go from -4 to whatever the height limit of the world is but divided by 16
+    */
     short y;
 } section;
 
@@ -31,10 +59,27 @@ typedef struct section{
  @brief A block structure with it's own coordinates and a string containing it's type
  @ingroup chunkParser
 */
-typedef struct block{
+typedef struct{
+    /*!
+     @var x
+     @brief The x position of the block
+    */
     int x;
+    /*!
+     @var y
+     @brief The y position of the block
+    */
     int y;
+    /*!
+     @var z
+     @brief The z position of the block
+    */
     int z;
+    /*!
+     @var type
+     @brief A string block type identifier
+     @note Shouldn't be NULL
+    */
     char* type;
 } block;
 

src/lib/generator.c

@@ -11,7 +11,7 @@
 
 model generateFromNbt(unsigned char* data, int dataSize, hashTable* materials, hashTable* objects, bool yLim, int upLim, int downLim, bool b, bool f, unsigned int side, int chunkX, int chunkZ){
     //Array of sections in this chunk
-    struct section sections[maxSections] = {0};
+    section sections[maxSections] = {0};
     int n = getSections(data, dataSize, sections);
     free(data);
     /*It is possible to not have to iterate over each block again, and do everything in a single loop.
@@ -54,7 +54,7 @@ model generateFromNbt(unsigned char* data, int dataSize, hashTable* materials, h
     return newModel;
 }
 
-cubeModel createCubeModel(struct section* sections, int sectionLen, hashTable* materials, bool yLim, int upLim, int downLim, unsigned int side, bool matCheck, int xOff, int zOff){
+cubeModel createCubeModel(section* sections, int sectionLen, hashTable* materials, bool yLim, int upLim, int downLim, unsigned int side, bool matCheck, int xOff, int zOff){
     cubeModel cubeModel = initCubeModel(16,16 * sectionLen, 16);
     for(int i = 0; i < sectionLen; i++){
         //create the block state array
@@ -64,7 +64,7 @@ cubeModel createCubeModel(struct section* sections, int sectionLen, hashTable* m
         for(int x = 0; x < 16; x++){
             for(int y = 0; y < 16; y++){
                 for(int z = 0; z < 16; z++){
-                    struct block newBlock = createBlock(x, y, z, states, sections[i]);
+                    block newBlock = createBlock(x, y, z, states, sections[i]);
                     if((newBlock.y > upLim || newBlock.y < downLim) && yLim){
                         newBlock.type = mcAir;
                     }
@@ -100,7 +100,7 @@ cubeModel createCubeModel(struct section* sections, int sectionLen, hashTable* m
     return cubeModel;
 }
 
-cube cubeFromBlock(struct block block, const unsigned int side, material* material){
+cube cubeFromBlock(block block, const unsigned int side, material* material){
     cube newCube = createGenericCube(side);
 
     newCube.x = block.x;

src/lib/generator.h

@@ -23,7 +23,7 @@
  @return The created cube object
  @ingroup generator
 */
-cube cubeFromBlock(struct block block, const unsigned int side, struct material* material);
+cube cubeFromBlock(block block, const unsigned int side, material* material);
 
 /*!
  @brief Creates a new cube based model object from a section array.
@@ -40,7 +40,7 @@ cube cubeFromBlock(struct block block, const unsigned int side, struct material*
  @return The created cube model object
  @ingroup generator
 */
-cubeModel createCubeModel(struct section* sections, int sectionLen, hashTable* materials, bool yLim, int upLim, int downLim, unsigned int side, bool matCheck, int xOff, int zOff);
+cubeModel createCubeModel(section* sections, int sectionLen, hashTable* materials, bool yLim, int upLim, int downLim, unsigned int side, bool matCheck, int xOff, int zOff);
 
 //Generally speaking i could just pass a whole chunk object from regionParser here, but I like the design of having that be completely separate
 

src/lib/hTable.c

@@ -12,9 +12,12 @@
 //taken from https://benhoyt.com/writings/hash-table-in-c/
 //i am not smart enough to come up with my own hash function
 
-//Generates a hash from a string
-uint64_t hash(const char* key)
-{
+/*!
+ @brief Generates a hash from a string
+ @param key the key to hash
+ @return a numeric hash
+*/
+static uint64_t hash(const char* key){
     uint64_t hash = FNV_OFFSET;
     for (const char* p = key; *p; p++) {
         hash ^= (uint64_t)(unsigned char)(*p);
@@ -23,7 +26,13 @@ uint64_t hash(const char* key)
     return hash;
 }
 
-struct hTableItem* initHashItem(const char* key, const void* value){
+/*!
+ @brief Initializes a hash item with the given values
+ @param key the key under which the value is held
+ @param value the value of the item
+ @return a newly allocated object
+*/
+static struct hTableItem* initHashItem(const char* key, const void* value){
     struct hTableItem* item = malloc(sizeof(struct hTableItem));
     item->key = malloc(strlen(key) + 1);
     strcpy(item->key, key);
@@ -40,7 +49,11 @@ hashTable* initHashTable(size_t size){
     return table;
 }
 
-void freeHashItem(struct hTableItem* item){
+/*!
+ @brief Frees a given hash item
+ @param item the item to free
+*/
+static void freeHashItem(struct hTableItem* item){
     if(item->next != NULL){
         freeHashItem(item->next);
     }

src/lib/hTable.h

@@ -14,8 +14,21 @@
  @ingroup hTable
 */
 struct hTableItem{
+    /*!
+     @var key
+     @brief the item key, used to identify the value in hash collisions
+    */
     char* key;
+    /*!
+     @var value
+     @brief whatever value the key is holding
+    */
     void* value;
+    /*!
+     @var next
+     @brief the next item in the linked list
+     @details can be NULL
+    */
     struct hTableItem* next;
 };
 
@@ -24,10 +37,23 @@ struct hTableItem{
  @brief A hash table storing keys and void* as values. For collision handling a linked list approach has been chosen
  @ingroup hTable
 */
-typedef struct hashTable{
+typedef struct{
+    /*!
+     @var items
+     @brief Nullable array of hash table items
+     @details Key hashes point into this array, and if the value under the hash isn't null then the item is inserted at the end of the underlying linked list
+    */
     struct hTableItem** items;
+    /*!
+     @var size
+     @brief The size of the array, not meant to be changed
+    */
     size_t size; //the size of the array
-    int count; //how many elements we have in the array
+    /*!
+     @var count
+     @brief how many elements we have in the array
+    */
+    int count;
 } hashTable;
 
 /*!