documentation(arena): Added comments to the functions and the arena-structure.

inc-c/ufn/ufn_arena.h

@@ -1,4 +1,5 @@
-// UFN Arena library. MIT-Licensed (c) Eric-Paul Ickhorn (epickh)
+// ufn_arena.h: An arena allocator with maximum usage limiter.
+// Under MIT-License. Copyright by Eric-Paul Ickhorn (epickh).
 
 #ifndef UFN_ARENA_H
 #define UFN_ARENA_H
@@ -9,6 +10,8 @@
 
 typedef struct ufn_arena ufn_arena_s;
 
+/// @brief Arena structure which is being acted upon by the arena
+///        functions. Manual modification may lead to undesired behaviour.
 struct ufn_arena
 {
     uint32_t capacity;
@@ -19,16 +22,42 @@ struct ufn_arena
     ufn_arena_s *continuation;
 };
 
+/// @brief Allocates a new arena tree with up to 'max_tree_size' .
+/// @warning No later but possibly earlier than when a total of
+///         'max_tree_size'  was distributed, the allocation function
+///         (ufn_arena_alloc) will return NULL.
+/// @param capacity Number of bytes to allocate in the first arena;
+///                 Determines how many bytes can be distributed.
+/// @param max_tree_size Maximum number of bytes to allocate for the
+///                      continuations. If this is less than or equal to
+///                      'capacity' * 2, the next continuation will be
+///                      the last one.
+/// @return Newly created dynamic arena.
 ufn_arena_s * ufn_new_dynamic_arena(uint32_t capacity, uint32_t max_tree_size);
+
+/// @brief Allocates a new arena with an immutable capacity.
+/// @warning If this arena's allocation is full,
+///          'ufn_arena_alloc' will return NULL!
+/// @note Internally calls 'ufn_new_dynamic_arena' with a maximum tree size of 0.
+/// @param capacity Number of bytes to allocate in the arena;
+///                 Determines how many bytes can be distributed.
+/// @return Newly created arena.
 ufn_arena_s * ufn_new_static_arena(uint32_t capacity);
+
+/// @brief Frees an arena and all its dynamic continuations.
+/// @param arena Arena to free.
 void ufn_free_arena(ufn_arena_s *arena);
 
+/// @brief Allocates a block of size 'size' in the arena 'arena'
+/// @warning Will return NULL if no memory block of length 'size'
+///          is available in the arena or any of the continuations.
+/// @param arena Arena to use for allocating 'size' bytes.
+/// @param size Number of bytes to allocate.
+/// @return Pointer to the newly allocated block.
 void * ufn_arena_alloc(ufn_arena_s *arena, uint32_t size);
 
-
+// END OF API, START OF IMPLEMENTATION.
-
 #ifdef UFN_IMPLEMENTATION
-
 #include <stdlib.h>
 
 ufn_arena_s * ufn_new_dynamic_arena(uint32_t capacity, uint32_t max_tree_size)
@@ -93,4 +122,5 @@ void * ufn_arena_alloc(ufn_arena_s *arena, uint32_t size)
 
 
 #endif // UFN_IMPLEMENTATION
+
 #endif // UFN_ARENA_H