From 6df8f4129a3acf9a1c402f381e2046d2052ab38e Mon Sep 17 00:00:00 2001 From: TCA Date: Sat, 20 Apr 2024 17:04:44 +0200 Subject: [PATCH] Documentation improvements --- README.md | 2 +- doc/index.md | 2 +- doc/pages/utilities.md | 8 ++ src/lib/chunkParser.h | 7 +- src/lib/errorDefs.h | 194 ++++++++++++++++++++--------------------- src/lib/model.c | 6 ++ src/lib/model.h | 11 +++ src/lib/regionParser.c | 6 +- src/lib/regionParser.h | 12 +++ 9 files changed, 143 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index c838d87..28d07af 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Multiple programs for Minecraft [save file data extraction](#data-extraction-utilities) and [3D model generation](#3d-model-generation) based on save files. Also several well documented custom C libraries with minimal prerequisites for wavefront 3d model handling and Minecraft save file handling. -[**User Manual**](https://tca166.github.io/mcSavefileParsers/md_doc_src_userManual.html) +[**User Manual**](https://tca166.github.io/mcSavefileParsers/md_doc_pages_userManual.html) ## Capabilities diff --git a/doc/index.md b/doc/index.md index 20c283a..de5e174 100644 --- a/doc/index.md +++ b/doc/index.md @@ -5,4 +5,4 @@ [![Windows](https://github.com/TCA166/mcSavefileParsers/actions/workflows/c-cppWin.yml/badge.svg)](https://github.com/TCA166/mcSavefileParsers/actions/workflows/c-cppWin.yml) Welcome to mcSavefileParsers documentation! -This is generally intended to be a resource for developers, but here's a [**User Manual**](https://tca166.github.io/mcSavefileParsers/md_doc_src_userManual.html) for the layman on how to use the utilities. +This is generally intended to be a resource for developers, but here's a [**User Manual**](https://tca166.github.io/mcSavefileParsers/md_doc_pages_userManual.html) for the layman on how to use the utilities. diff --git a/doc/pages/utilities.md b/doc/pages/utilities.md index d8c0ebb..eb5d632 100644 --- a/doc/pages/utilities.md +++ b/doc/pages/utilities.md @@ -28,6 +28,14 @@ This program extracts only a single chunk with the given chunk coordinates into chunkExtractor ``` +### blockPrint + +This program prints out quantities of specific blocks in a chunk + +```Bash +blockPrint +``` + ## 3D model generation Multiple tools that can take in Minecraft related files as input and create 3D representations of your worlds diff --git a/src/lib/chunkParser.h b/src/lib/chunkParser.h index 6327046..d206f4a 100644 --- a/src/lib/chunkParser.h +++ b/src/lib/chunkParser.h @@ -115,7 +115,10 @@ typedef struct{ @param sz The size of the nbt file data @param sections The array of sections to be filled @return The number of sections extracted - @exception plenty of things can go wrong, check for 0 + @exception cNBTError if the nbt data is invalid + @exception nbtTypeError if the nbt data is of the wrong type + @exception nbtTagError if the nbt data is missing a tag + @exception overflowError if the nbt data is too large @ingroup chunkParser */ unsigned int getSections(unsigned char* nbtFileData, long sz, section* sections); @@ -126,7 +129,7 @@ unsigned int getSections(unsigned char* nbtFileData, long sz, section* sections) @param s The section to create the block states from @param outLen The length of the block states array @return The block states array, or NULL if it cannot be created - @exception malloc can fail: check for NULL + @exception mallocError if the block states array cannot be allocated @ingroup chunkParser */ unsigned int* getBlockStates(section s, int* outLen); diff --git a/src/lib/errorDefs.h b/src/lib/errorDefs.h index 7c09b82..5b46bff 100644 --- a/src/lib/errorDefs.h +++ b/src/lib/errorDefs.h @@ -1,8 +1,7 @@ /*! - * @file errorDefs.h - * @brief Contains error definitions for the project - * - * @details Within this project errors are handled by calling one of these macros. They print an error message to stderr, set errno to a specific value and exit the program with EXIT_FAILURE. + @file errorDefs.h + @brief Contains error definitions for the project + @details Within this project errors are handled by calling one of these macros. They print an error message to stderr, set errno to a specific value and exit the program with EXIT_FAILURE. */ #include @@ -13,6 +12,7 @@ @defgroup mcErrno Error Reporting @brief A shared error reporting system @details This shared error reporting system is used to report errors in the project using a global variable mcErrno of type mcError_t + @see errorDefs, warningDefs on how to work within the system */ /*! @@ -107,170 +107,170 @@ extern mcError_t mcErrno; errno = 0; /*! - * @def cNBTError - * @brief Reports an error encountered while parsing an NBT file - * @param filename The name of the file that caused the error - * @ingroup errorDefs + @def cNBTError + @brief Reports an error encountered while parsing an NBT file + @param filename The name of the file that caused the error + @ingroup errorDefs */ #define cNBTError(filename) \ mcErrno = cNBTError; \ fprintf(stderr, "cNBT encountered an error while parsing %s", filename); \ /*! - * @def nbtTypeError - * @brief Reports an error when the tag has a different type - * @param type The current type of the tag - * @param expected The expected type of the tag - * @ingroup errorDefs + @def nbtTypeError + @brief Reports an error when the tag has a different type + @param type The current type of the tag + @param expected The expected type of the tag + @ingroup errorDefs */ #define nbtTypeError(type, expected) \ mcErrno = nbtTypeError; \ fprintf(stderr, "Expected type:%d, current type:%d.", expected, type);\ /*! - * @def nbtTagError - * @brief Reports an error when the needed tag is missing - * @param tag The name of the missing tag - * @ingroup errorDefs + @def nbtTagError + @brief Reports an error when the needed tag is missing + @param tag The name of the missing tag + @ingroup errorDefs */ #define nbtTagError(tag) \ mcErrno = nbtTagError; \ fprintf(stderr, "Tag %s was not found.", tag);\ /*! - * @def fileError - * @brief Reports an error related to C syscalls regarding files - * @param filename The name of the file - * @param action The action being performed on the file - * @ingroup errorDefs + @def fileError + @brief Reports an error related to C syscalls regarding files + @param filename The name of the file + @param action The action being performed on the file + @ingroup errorDefs */ #define fileError(filename, action) \ mcErrno = fileError; \ fprintf(stderr, "File %s couldn't be " action ".", filename); \ /*! - * @def parsingError - * @brief Reports an error encountered during the parsing of a file - * @param filename The name of the file being parsed - * @param action The action being performed on the file - * @ingroup errorDefs + @def parsingError + @brief Reports an error encountered during the parsing of a file + @param filename The name of the file being parsed + @param action The action being performed on the file + @ingroup errorDefs */ #define parsingError(filename, action) \ mcErrno = parsingError; \ fprintf(stderr, "Error encountered during " action " of %s.", filename); \ /*! - * @def statesWarning - * @brief Reports a warning when a minecraft block state is larger than the palette - * @param state The current state value - * @param paletteLen The length of the palette - * @param block The name of the block - * @ingroup errorDefs + @def statesWarning + @brief Reports a warning when a minecraft block state is larger than the palette + @param state The current state value + @param paletteLen The length of the palette + @param block The name of the block + @ingroup errorDefs */ #define statesWarning(state, paletteLen, block) \ mcErrno = statesWarning; \ fprintf(stderr, "%d >= %ld:states warning\n", state, paletteLen); \ /*! - * @def argError - * @brief Reports an error when an invalid amount of sub-arguments is provided - * @param argName The name of the argument - * @param argCount The required number of arguments - * @ingroup errorDefs + @def argError + @brief Reports an error when an invalid amount of sub-arguments is provided + @param argName The name of the argument + @param argCount The required number of arguments + @ingroup errorDefs */ #define argError(argName, argCount) \ mcErrno = argError; \ fprintf(stderr, "Incorrect number of arguments." argName " requires " argCount " arguments to follow."); \ /*! - * @def argCountError - * @brief Reports an error when an invalid amount of arguments is provided - * @param usage The usage of the program - * @ingroup errorDefs + @def argCountError + @brief Reports an error when an invalid amount of arguments is provided + @param usage The usage of the program + @ingroup errorDefs */ #define argCountError(usage) \ mcErrno = argCountError; \ fprintf(stderr, "Invalid number of arguments was provided\n" usage "\n"); \ /*! - * @def dirError - * @brief Reports an error when a directory cannot be opened - * @param dirname The name of the directory - * @ingroup errorDefs + @def dirError + @brief Reports an error when a directory cannot be opened + @param dirname The name of the directory + @ingroup errorDefs */ #define dirError(dirname) \ mcErrno = dirError; \ fprintf(stderr, "Directory %s couldn't be opened.\n", dirname); \ /*! - * @def materialWarning - * @brief Reports a warning when the material for a type couldn't be found in the mtl file - * @param type The type of the material - * @ingroup warningDefs + @def materialWarning + @brief Reports a warning when the material for a type couldn't be found in the mtl file + @param type The type of the material + @ingroup warningDefs */ #define materialWarning(type) \ mcErrno = materialWarning; \ fprintf(stdout, "Material for %s couldn't be found in the mtl file.\n", type); /*! - * @def vertexWarning - * @brief Reports a warning when there is a possible vertex-face mismatch in an object - * @param objName The name of the object - * @ingroup warningDefs + @def vertexWarning + @brief Reports a warning when there is a possible vertex-face mismatch in an object + @param objName The name of the object + @ingroup warningDefs */ #define vertexWarning(objName) \ mcErrno = vertexWarning; \ fprintf(stderr, "A possible vertex-face mismatch in object %s\n", objName); /*! - * @def argValError - * @brief Reports an error when an invalid value of an argument is provided - * @param arg The name of the argument - * @ingroup errorDefs + @def argValError + @brief Reports an error when an invalid value of an argument is provided + @param arg The name of the argument + @ingroup errorDefs */ #define argValError(arg) \ mcErrno = argValError; \ fprintf(stderr, "Invalid " arg " argument value.\n"); \ /*! - * @def pipeError - * @brief Reports an error when something goes wrong with a pipe - * @param pipe The name of the pipe - * @param operation The operation being performed on the pipe - * @ingroup errorDefs + @def pipeError + @brief Reports an error when something goes wrong with a pipe + @param pipe The name of the pipe + @param operation The operation being performed on the pipe + @ingroup errorDefs */ #define pipeError(pipe, operation) \ mcErrno = pipeError; \ fprintf(stderr, "Pipe " pipe " " operation " failed.\n"); \ /*! - * @def forkError - * @brief Reports an error when fork fails - * @param fork The name of the fork - * @ingroup errorDefs + @def forkError + @brief Reports an error when fork fails + @param fork The name of the fork + @ingroup errorDefs */ #define forkError(fork) \ mcErrno = forkError; \ fprintf(stderr, "Fork " fork " failed.\n"); \ /*! - * @def shmError - * @brief Reports an error when something goes wrong with shared memory - * @param shm The name of the shared memory - * @ingroup errorDefs + @def shmError + @brief Reports an error when something goes wrong with shared memory + @param shm The name of the shared memory + @ingroup errorDefs */ #define shmError(shm) \ mcErrno = shmError; \ fprintf(stderr, shm " failed.\n"); \ /*! - * @def localizedFileError - * @brief Reports an error with a specific position in a file - * @param pos The position in the file - * @param fileName The name of the file - * @param action The action being performed on the file - * @extends fileError - * @ingroup errorDefs + @def localizedFileError + @brief Reports an error with a specific position in a file + @param pos The position in the file + @param fileName The name of the file + @param action The action being performed on the file + @extends fileError + @ingroup errorDefs */ #define localizedFileError(pos, fileName, action) \ fprintf(stderr, "At %lu ", pos); \ @@ -278,23 +278,23 @@ extern mcError_t mcErrno; mcErrno = localizedFileError; /*! - * @def semaphoreError - * @brief Reports an error when something goes wrong with a semaphore - * @param sem The name of the semaphore - * @param action The action being performed on the semaphore - * @ingroup errorDefs + @def semaphoreError + @brief Reports an error when something goes wrong with a semaphore + @param sem The name of the semaphore + @param action The action being performed on the semaphore + @ingroup errorDefs */ #define semaphoreError(sem, action) \ mcErrno = semaphoreError; \ fprintf(stderr, "Semaphore " sem " couldn't " action "\n"); \ /*! - * @def mallocError - * @brief Reports an error when detecting NULL return value of malloc - * @param malloc The name of the malloc - * @param size The size of the memory being allocated - * @extends perror - * @ingroup errorDefs + @def mallocError + @brief Reports an error when detecting NULL return value of malloc + @param malloc The name of the malloc + @param size The size of the memory being allocated + @extends perror + @ingroup errorDefs */ #define mallocError(malloc, size) \ mcErrno = mallocError; \ @@ -303,11 +303,11 @@ extern mcError_t mcErrno; perror("Malloc error"); \ /*! - * @def overflowError - * @brief Reports an error when an overflow condition has been detected - * @param type The type of the overflow - * @extends EOVERFLOW - * @ingroup errorDefs + @def overflowError + @brief Reports an error when an overflow condition has been detected + @param type The type of the overflow + @extends EOVERFLOW + @ingroup errorDefs */ #define overflowError(type) \ mcErrno = overflowError; \ @@ -315,9 +315,9 @@ extern mcError_t mcErrno; errno = EOVERFLOW; \ /*! - * @def stringError - * @brief Reports an error when there is an issue with string operations - * @ingroup errorDefs + @def stringError + @brief Reports an error when there is an issue with string operations + @ingroup errorDefs */ #define stringError(function) \ mcErrno = stringError; \ diff --git a/src/lib/model.c b/src/lib/model.c index 4a2e949..e6fdc94 100644 --- a/src/lib/model.c +++ b/src/lib/model.c @@ -426,6 +426,9 @@ char* generateModel(const model* thisModel, size_t* outSize, const char* materia if(thisObject->m != NULL){ //add the usemtl line fileContents = appendMtlLine(thisObject->m->name, fileContents, outSize, &alloc); + if(fileContents == NULL){ + return NULL; + } } int x = (int)thisObject->x; int y = (int)thisObject->y; @@ -482,6 +485,9 @@ char* generateModel(const model* thisModel, size_t* outSize, const char* materia objFace face = thisObject->faces[i]; if(face.m != NULL){ fileContents = appendMtlLine(face.m->name, fileContents, outSize, &alloc); + if(fileContents == NULL){ + return NULL; + } } size_t size = 4; for(int m = 0; m < face.vertexCount; m++){ diff --git a/src/lib/model.h b/src/lib/model.h index 9d11cca..4d41e7e 100644 --- a/src/lib/model.h +++ b/src/lib/model.h @@ -378,6 +378,7 @@ unsigned int cullFaces(cubeModel* thisModel, bool cullChunkBorder, hashTable* sp @param m The cubeModel to convert @param specialObjects A hash table of special objects to insert into the model @return The new model reference + @exception mallocError if memory cannot be allocated @ingroup model */ model cubeModelToModel(const cubeModel* m, hashTable* specialObjects); @@ -393,6 +394,9 @@ model cubeModelToModel(const cubeModel* m, hashTable* specialObjects); @param materialFileName The name of the material file @param offset The offset of the model @return The generated model + @exception stringError if the string operations fail + @exception mallocError if memory cannot be allocated + @exception overflowError if the model is too large @ingroup model */ char* generateModel(const model* thisModel, size_t* outSize, const char* materialFileName, offset_t* offset); @@ -427,6 +431,8 @@ cubeFace* newCubeFace(int a, int b, int c, int d); @details Allocates necessary memory for material type strings. @param filename The name of the mtl file @return Returns a new reference to a material hash table. + @exception fileError if the file operations fail + @exception mallocError if memory cannot be allocated @ingroup model */ hashTable* getMaterials(char* filename); @@ -464,6 +470,10 @@ object deCubeObject(cube* c); @param materials The materials hash table to use for the model @param side The side of the block to render @return The hash table of objects + @exception fileError if the file operations fail + @exception mallocError if memory cannot be allocated + @exception parseError if the wavefront file is invalid + @exception vertexWarning if a vertex is invalid @ingroup model */ hashTable* readWavefront(char* filename, hashTable* materials, unsigned int side); @@ -510,6 +520,7 @@ cube createGenericCube(unsigned int side); @param m The model to convert @param type The type of the object @return The optimized object + @exception mallocError if memory cannot be allocated @ingroup model */ object modelToObject(const model* m, const char* type); diff --git a/src/lib/regionParser.c b/src/lib/regionParser.c index a5b1928..a13cce6 100644 --- a/src/lib/regionParser.c +++ b/src/lib/regionParser.c @@ -182,8 +182,7 @@ chunk* getChunks(FILE* regionFile){ */ int res = getChunkData(&chunks[i], regionFile, "region file"); if(res < 0){ - fprintf(stderr, "Inflate returned %d ", res); - perror("Decompression failed."); + return NULL; } } } @@ -214,8 +213,7 @@ chunk getChunk(int x, int z, FILE* regionFile, char* regionFileName){ } int res = getChunkData(&result, regionFile, regionFileName); if(res < 0){ - fprintf(stderr, "Inflate returned %d ", res); - perror("Decompression failed."); + return result; } return result; } diff --git a/src/lib/regionParser.h b/src/lib/regionParser.h index 731b8aa..6ba08f2 100644 --- a/src/lib/regionParser.h +++ b/src/lib/regionParser.h @@ -126,6 +126,10 @@ typedef struct{ @param z The z coordinate of the chunk @param regionFile The region file to read from @param regionFileName The name of the region file + @exception fileError if file operations fail + @exception mallocError if malloc fails + @exception parsingError if region file is invalid + @exception localizedFileError if file operations fail @return The chunk object */ chunk getChunk(int x, int z, FILE* regionFile, char* regionFileName); @@ -136,6 +140,10 @@ chunk getChunk(int x, int z, FILE* regionFile, char* regionFileName); @return Returns a dynamic array of chunks with 1024 chunks. @note High-er level function that does error handling on it's own. @param regionFile The region file to read from + @exception fileError if file operations fail + @exception mallocError if malloc fails + @exception parsingError if region file is invalid + @exception localizedFileError if file operations fail @ingroup regionParser */ chunk* getChunks(FILE* regionFile); @@ -147,6 +155,10 @@ chunk* getChunks(FILE* regionFile); @param x The x coordinate of the chunk @param z The z coordinate of the chunk @return The chunk object + @exception fileError if file operations fail + @exception mallocError if malloc fails + @exception parsingError if region file is invalid + @exception localizedFileError if file operations fail @ingroup regionParser */ chunk extractChunk(char* regionDirPath, int x, int z);