Added doxygen documentation

.gitignore

@@ -22,4 +22,5 @@ mtlGen
 !license.txt
 *Check*
 tests/benchmark
-mtlFiles
+mtlFiles
+doc/build/*

.vscode/settings.json

@@ -19,7 +19,10 @@
         "types.h": "c",
         "semaphore.h": "c",
         "wait.h": "c",
-        "generator.h": "c"
+        "generator.h": "c",
+        "stdbool.h": "c",
+        "htable.h": "c",
+        "stdlib.h": "c"
     },
     "cSpell.words": [
         "blockstates",

Makefile

@@ -119,4 +119,7 @@ check: hTable.o regionParser.o chunkParser.o cNBT.o model.o
 	#model tests
 	checkmk tests/model.check > tests/modelCheck.c
 	gcc tests/modelCheck.c model.o hTable.o -lcheck -lm $(SUBUNIT) -o tests/modelCheck
-	./tests/modelCheck
+	./tests/modelCheck
+
+doc: src/lib/*.h src/*.c src/lib/*.c doc/Doxyfile.conf
+	doxygen ./doc/Doxyfile.conf

src/chunkExtractor.c

@@ -1,3 +1,9 @@
+/*!
+ @file chunkExtractor.c
+ @brief Extracts specific chunks from all region files
+ @details This program extracts specific chunks from all region files   
+*/
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>
@@ -8,7 +14,13 @@
 #include "./lib/errorDefs.h"
 #include "./lib/regionParser.h"
 
-//Program for extracting specific chunks from all region files
+/*!
+ @brief Extracts a chunk from a region file
+ @details Loads a chunk from a region file using the regionParser library, then writes it to a file using extractChunk.
+ @see regionParser.h
+ @see @ref extractChunk
+ @return The chunk object
+*/
 int main(int argc, char** argv){
     if(argc < 3){
         argCountError();

src/lib/chunkParser.c

@@ -12,11 +12,31 @@
 
 #include <inttypes.h>
 
+/*!
+ @def createMask
+ @brief Creates a mask for a given bit range
+ @param startBit The starting bit
+ @param X The number of bits
+*/
 #define createMask(startBit, X) ((((uint64_t)1) << X) - 1) << startBit
 
+/*!
+ @def statesFormula
+ @brief Calculates the index of a block in a section
+ @param x The x coordinate
+ @param y The y coordinate
+ @param z The z coordinate
+*/
 #define statesFormula(x, y, z) (y*16*16) + (z*16) + x
 
-char* getProperty(const char* property, nbt_node* tree){
+/*!
+ @brief Gets a property from a compound node
+ @details Gets a property from a compound node
+ @param property The name of the property
+ @param tree The compound node
+ @return The property value
+*/
+static inline char* getProperty(const char* property, nbt_node* tree){
     char* result = NULL;
     nbt_node* colorNode = nbt_find_by_name(tree, property);
     if(colorNode != NULL){
@@ -26,7 +46,15 @@ char* getProperty(const char* property, nbt_node* tree){
     return result;
 }
 
-char* appendProperty(char* string, char* property, const char* propertyName){
+/*!
+ @brief Appends a property to a string
+ @details Appends a property to a string
+ @param string The string to append to
+ @param property The property to append
+ @param propertyName The name of the property
+ @return The new string
+*/
+static inline char* appendProperty(char* string, char* property, const char* propertyName){
     string = realloc(string, strlen(string) + 3 + strlen(property) + strlen(propertyName));
     strcat(string, propertyName);
     strcat(string, "=");
@@ -243,7 +271,15 @@ block createBlock(int x, int y, int z, unsigned int* blockStates, section parent
     return newBlock;
 }
 
-bool contains(char** arr, char* str, int arrLen){
+/*!
+ @brief Checks if a string is in an array
+ @details Checks if a string is in an array
+ @param arr The array to check
+ @param str The string to check for
+ @param arrLen The length of the array
+ @return If the string is in the array
+*/
+static inline bool contains(char** arr, char* str, int arrLen){
     for(int i = 0; i < arrLen; i++){
         if(strcmp(arr[i], str) == 0){
             return true;

src/lib/chunkParser.h

@@ -1,7 +1,23 @@
+/*!
+ @file chunkParser.h
+ @brief Contains functions for parsing chunk data
+ @details This file contains functions for parsing chunk data
+*/
+
+/*!
+ @defgroup chunkParser Chunk Parser
+ @ingroup chunkParser
+ @brief Chunk data parsing functions
+*/
+
 #include <stdbool.h>
 #include <inttypes.h>
 
-//16x16x16 big section of a chunk
+/*!
+ @struct section
+ @brief 16x16x16 section of a chunk
+ @ingroup chunkParser
+*/
 typedef struct section{
     //we ignore the biomes because we don't need that data
     uint64_t* blockData; //raw nbt file block data
@@ -11,40 +27,78 @@ typedef struct section{
     short y;
 } section;
 
-//A block structure with it's own coordinates and a string containing it's type
+/*!
+ @struct block
+ @brief A block structure with it's own coordinates and a string containing it's type
+ @ingroup chunkParser
+*/
 typedef struct block{
     int x;
     int y;
     int z;
     char* type;
 } block;
 
+/*!
+ @def maxSections
+ @brief The maximum number of sections in a chunk
+ @details This is the maximum number of sections in a chunk, which is 24 as of 1.17
+ @ingroup chunkParser
+*/
 #define maxSections 24
 
 #define mcAir "minecraft:air"
 #define minY -64
 
-/*
-Extracts sections from nbtFileData of size sz into sections array and returns the number of extracted sections
-blockData, blockPalette and elements of blockPalette are allocated on the heap and will need to be freed
+/*!
+ @brief Extracts sections from raw nbtFileData of size into sections array
+ @details blockData, blockPalette and elements of blockPalette are allocated on the heap and will need to be freed
+ @param nbtFileData The raw nbt file data
+ @param sz The size of the nbt file data
+ @param sections The array of sections to be filled
+ @return The number of sections extracted
+ @ingroup chunkParser
 */
 unsigned int getSections(unsigned char* nbtFileData, long sz, section* sections);
 
-/*
-Creates the block states array based on a section.
-Returns NULL if it cannot be created. Be sure to free the result once you are done with it.
-outLen can be NULL.
+/*!
+ @brief Creates the block states array based on a section.
+ @details Returns NULL if it cannot be created. Be sure to free the result once you are done with it.
+ @param s The section to create the block states from
+ @param outLen The length of the block states array
+ @return The block states array
+ @ingroup chunkParser
 */
 unsigned int* getBlockStates(section s, int* outLen);
 
-//Creates a block struct based on the struct coordinates, the blockstates array and the parent section
+/*!
+ @brief Creates a block struct based on the struct coordinates, the blockstates array and the parent section
+ @param x The x coordinate of the block
+ @param y The y coordinate of the block
+ @param z The z coordinate of the block
+ @param blockStates The block states array
+ @param parentSection The parent section of the block
+ @return The block struct
+ @ingroup chunkParser
+*/
 block createBlock(int x, int y, int z, unsigned int* blockStates, section parentSection);
 
-/*
-Returns an array of strings containing a complete total block palette
-The only memory it allocates is the returned array
+/*!
+ @brief Returns an array of strings containing a complete total block palette
+ @details The only memory it allocates is the returned array
+ @param sections The sections to create the global palette from
+ @param len The length of the sections array
+ @param outLen The length of the returned array
+ @param freeSectionPalettes Whether to free the section palettes
+ @return The global palette
+ @ingroup chunkParser
 */
 char** createGlobalPalette(section* sections, int len, int* outLen, bool freeSectionPalettes);
 
-//Frees all the allocated memory by getSections
+/*!
+ @brief Frees all the allocated memory by getSections
+ @param sections The sections to free
+ @param sectionLen The length of the sections array
+ @ingroup chunkParser
+*/
 void freeSections(section* sections, int sectionLen);