Documentation improvements

TCA166 · Apr 20, 2024 · 6df8f41 · 6df8f41
1 parent bb956b7
commit 6df8f41
Show file tree

Hide file tree

Showing 9 changed files with 143 additions and 105 deletions.
diff --git 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
@@ -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
@@ -28,6 +28,14 @@ This program extracts only a single chunk with the given chunk coordinates into
 chunkExtractor <path to region directory> <x> <z>
 ```
 
+### blockPrint
+
+This program prints out quantities of specific blocks in a chunk
+
+```Bash
+blockPrint <path to a chunk nbt file>
+```
+
 ## 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
@@ -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
@@ -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 <stdlib.h>
@@ -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,194 +107,194 @@ 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); \
     fileError(fileName, action); \
     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,21 +303,21 @@ 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; \
     fprintf(stderr, "An overflow condition has been detected of " type "."); \
     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; \