docs(allocator): wrote documentation for allocator

Docs/Allocator.md

@@ -0,0 +1,107 @@
+# Allocator
+
+This part of the library implements a custom heap allocator which efficiently manages heap memory for both windows and linux devices.
+
+## Featurs
+
+* Memory allocation
+* Freeing of memory
+* Zeroing memory on allocation
+* Reallocating memory from existing memory
+
+## Usage
+
+### Allocating
+
+When using the library you can allocate memory using the `hallocy_allocate`, `hallocy_malloc` or `hallocy_calloc` functions. It is recommended to use `hallocy_malloc` and `hallocy_calloc` for clarity. You could also allocate memory using the `hallocy_realloc`, but this is not recommended as this is slightly slower than using the `hallocy_malloc` function.
+
+### Freeing
+
+When you are done with the allocated memory it is important you free it using the `hallocy_free` function. Freeing memory that is not used will not only prevent memory leaks, but also makes future allocations faster as the freeed memory blocks can be reused.
+
+### Error handling
+
+The `hallocy_allocate`, `hallocy_malloc`, `hallocy_calloc` and `hallocy_realloc` all return `NULL` on finding an error. These functions can return `NULL` when there is no memory available, parameters that where given where invalid or other reasons. 
+
+The `hallocy_free` function returns a `HallocyError` containing the reason for the error. When calling any Hallocy function it is important you handle these errors to prevent possible problems like trying to access an invalid memory address.
+
+## Functions
+
+### Allocate 
+
+Allocates memory on the heap and can zero the memory on allocation.
+
+```c
+void *hallocy_allocate(size_t size, bool zero_memory);
+```
+
+- `size`: The amount of bytes to allocate.
+- `zero_memory`: Zero's memory when `true`.
+
+### Malloc
+
+Allocates memory on the heap.
+
+```c
+static inline void *hallocy_malloc(size_t size) { return hallocy_allocate(size, false); }
+```
+
+- `size`: The amount of bytes to allocate.
+
+### Calloc
+
+Allocates memory and zero's it on allocation.
+
+```c
+static inline void *hallocy_calloc(size_t size, size_t count) { return  hallocy_allocate(size * count, true); }
+```
+
+- `size`: Size of one element in bytes.
+- `count`: The amount of elements to allocate memory for.
+
+### Realloc
+
+Reallocates more memory for existing allocations.
+
+```c
+void *hallocy_realloc(void *memory_pointer, size_t size);
+```
+
+- `memory_pointer`: Pointer to already allocated heap memory.
+- `size`: The size of the new allocated memory.
+
+### Free
+
+Free's heap memory.
+
+```c
+HallocyError hallocy_free(void *pointer);
+```
+
+- `pointer`: The pointer to allocated heap memory to free.
+
+## Example usage
+
+```c
+#include <Hallocy/Core/Allocator.h>
+#include <Hallocy/Utils/Error.h>
+
+int main() {
+    char *allocated_memory = hallocy_malloc(128 * sizeof(char));
+    if (allocated_memory == NULL) {
+        return -1;
+    }
+
+    allocated_memory = hallocy_realloc(allocated_memory, 256);
+    if (allocated_memory == NULL) {
+        return -1;
+    }
+
+    HallocyError error = hallocy_free(allocated memory);
+    if (error != HALLOCY_ERROR_NONE) {
+        return -1; // Check type of error here instead of returning -1 imidiatly.
+    }
+
+    return 0;
+}
+```

Docs/Index.md

@@ -0,0 +1,12 @@
+# Library documentation
+
+Welcome to the documentation of the **Hallocy C library**!
+
+This documentation is split into several parts:
+
+- [Allocator](Allocator.md)
+- [Memory management](MemoryManagement.md)
+
+Use this as a guide for using the library within your existing project.
+
+> For installation and initial setup, please refer to the [README.md](../README.md).

README.md

@@ -60,4 +60,6 @@ Ensure you have the following installed on your system:
 
 ## Using the library
 
-The library file can be found in the `./Build/Release` folder as Hallocy.lib for windows and in `./Build` folder as libHallocy.a for linux. To use the library file you will need to copy the Hallocy folder containing the header files and follow the setup process for a library in the build system you are using. 
+The library file can be found in the `./Build/Release` folder as Hallocy.lib for windows and in `./Build` folder as libHallocy.a for linux. To use the library file you will need to copy the Hallocy folder containing the header files and follow the setup process for a library in the build system you are using. 
+
+For more info about how to use the library see the documentation folder named `Docs`.