Checking documentation is suitable
I've just started splitting my code into multiple files and thought I would check if the comments I'm using are suitable enough for documenting my code, I welcome all suggestions here.
Here's the first one that I don't intend to change the API on
Code:
typedef struct space {
size_t given;
void *block;
} space_t;
/** @brief Memory allocater, usually via malloc, realloc & free
* @param err Thread safe passback of encountered errors, in the event
* malloc or realloc fail then this will be filled with whatever errno
* holds at that time
* @param space Desitination of allocated memory, initialise with {0}
* @param want Amount of memory you want
* @param dir Direction to restraint allocation to, see below defines
* @return allocated memory or NULL, nothing in space parameter will be
* overwritten if memory failes to be retrieved, if freed will be
* cleared
* @example if ( !(txt = change_space(
* &ret, &text, BUFSIZ, 0 )) ) {...}
**/
void* change_space( int *err, space_t *space, size_t want, int dir );
#define need_space( err, space, want )\
change_space( err, space, want, 0 )
#define more_space( err, space, want )\
change_space( err, space, want, 1 )
#define less_space( err, space, want )\
change_space( err, space, want, -1 )
#define free_space( err, space )\
change_space( err, space, 0, 0 )
typedef size_t node_t;
typedef struct nodes {
node_t count;
node_t total;
space_t space;
} nodes_t;
/** @brief Node allocater, passes over to change_space() after doing
* calculations
* @param err Thread safe passback of encountered errors, in the event
* malloc or realloc fail then this will be filled with whatever errno
* holds at that time
* @param nodes Desitination of allocated memory, initialise with {0}
* @param Nsize size of each node, sizeof(T) is best practice here
* @param want Number of nodes you want
* @param dir Direction to restraint allocation to, see below defines
* @return allocated memory or NULL, nothing in nodes parameter will be
* overwritten if memory failes to be retrieved, if freed will be
* cleared
* @example if ( !(txt = change_space(
* &ret, &text, sizeof(wchar_t), BUFSIZ, 0 )) ) {...}
**/
void* change_nodes(
int *err, nodes_t *nodes, size_t Nsize, size_t want, int dir );
#define need_nodes( T, err, nodes, want )\
(T*)change_nodes( err, nodes, sizeof(T), want, 0 )
#define more_nodes( T, err, nodes, want )\
(T*)change_nodes( err, nodes, sizeof(T), want, 1 )
#define less_nodes( T, err, nodes, want )\
(T*)change_nodes( err, nodes, sizeof(T), want, -1 )
#define free_nodes( T, err, nodes )\
(T*)change_nodes( err, nodes, sizeof(T), 0, 0 )
