changeset
refine docs for allocator.h - issue #548
Sat, 04 Jan 2025 13:34:37 +0100
- author
- Mike Becker <universe@uap-core.de>
- date
- Sat, 04 Jan 2025 13:34:37 +0100
- changeset 1085
- b8e0b4130cc3
- parent 1084
- 0bcd71d2615a
- child 1086
- 4c6ea8a10acd
refine docs for allocator.h - issue #548
| src/cx/allocator.h | file | annotate | diff | comparison | revisions |
--- a/src/cx/allocator.h Sat Jan 04 12:31:28 2025 +0100 +++ b/src/cx/allocator.h Sat Jan 04 13:34:37 2025 +0100 @@ -26,7 +26,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ /** - * \file allocator.h + * @file allocator.h * Interface for custom allocators. */ @@ -46,8 +46,6 @@ /** * The allocator's malloc() implementation. */ - cx_attr_nonnull - cx_attr_nodiscard cx_attr_allocsize(2) void *(*malloc)( void *data, size_t n @@ -56,8 +54,6 @@ /** * The allocator's realloc() implementation. */ - cx_attr_nodiscard - cx_attr_allocsize(3) void *(*realloc)( void *data, void *mem, @@ -67,8 +63,6 @@ /** * The allocator's calloc() implementation. */ - cx_attr_nodiscard - cx_attr_allocsize(2, 3) void *(*calloc)( void *data, size_t nelem, @@ -78,7 +72,6 @@ /** * The allocator's free() implementation. */ - cx_attr_nonnull_arg(1) void (*free)( void *data, void *mem @@ -113,7 +106,7 @@ * Function pointer type for destructor functions. * * A destructor function deallocates possible contents and MAY free the memory - * pointed to by \p memory. Read the documentation of the respective function + * pointed to by @p memory. Read the documentation of the respective function * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in * that particular implementation. * @@ -125,7 +118,7 @@ * Function pointer type for destructor functions. * * A destructor function deallocates possible contents and MAY free the memory - * pointed to by \p memory. Read the documentation of the respective function + * pointed to by @p memory. Read the documentation of the respective function * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in * that particular implementation. * @@ -141,12 +134,14 @@ * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. * - * \par Error handling - * \c errno will be set by realloc() on failure. + * @par Error handling + * @c errno will be set by realloc() on failure. * * @param mem pointer to the pointer to allocated block * @param n the new size in bytes - * @return zero on success, non-zero on failure + * @retval zero success + * @retval non-zero failure + * @see cx_reallocatearray() */ cx_attr_nonnull cx_attr_nodiscard @@ -159,16 +154,18 @@ * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. * - * The size is calculated by multiplying \p nemb and \p size. + * The size is calculated by multiplying @p nemb and @p size. * - * \par Error handling - * \c errno will be set by realloc() on failure or when the multiplication of - * \p nmemb and \p size overflows. + * @par Error handling + * @c errno will be set by realloc() on failure or when the multiplication of + * @p nmemb and @p size overflows. * * @param mem pointer to the pointer to allocated block * @param nmemb the number of elements * @param size the size of each element - * @return zero on success, non-zero on failure + * @retval zero success + * @retval non-zero failure + * @see cx_reallocate() */ cx_attr_nonnull cx_attr_nodiscard @@ -182,12 +179,14 @@ * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. * - * \par Error handling - * \c errno will be set by realloc() on failure. + * @par Error handling + * @c errno will be set by realloc() on failure. * - * @param mem pointer to the pointer to allocated block - * @param n the new size in bytes - * @return zero on success, non-zero on failure + * @param mem (@c void**) pointer to the pointer to allocated block + * @param n (@c size_t) the new size in bytes + * @retval zero success + * @retval non-zero failure + * @see cx_reallocatearray() */ #define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n) @@ -195,16 +194,17 @@ * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. * - * The size is calculated by multiplying \p nemb and \p size. + * The size is calculated by multiplying @p nemb and @p size. + * + * @par Error handling + * @c errno will be set by realloc() on failure or when the multiplication of + * @p nmemb and @p size overflows. * - * \par Error handling - * \c errno will be set by realloc() on failure or when the multiplication of - * \p nmemb and \p size overflows. - * - * @param mem pointer to the pointer to allocated block - * @param nmemb the number of elements - * @param size the size of each element - * @return zero on success, non-zero on failure + * @param mem (@c void**) pointer to the pointer to allocated block + * @param nmemb (@c size_t) the number of elements + * @param size (@c size_t) the size of each element + * @retval zero success + * @retval non-zero failure */ #define cx_reallocatearray(mem, nmemb, size) \ cx_reallocatearray((void**)(mem), nmemb, size) @@ -212,7 +212,7 @@ /** * Free a block allocated by this allocator. * - * \note Freeing a block of a different allocator is undefined. + * @note Freeing a block of a different allocator is undefined. * * @param allocator the allocator * @param mem a pointer to the block to free @@ -224,7 +224,7 @@ ); /** - * Allocate \p n bytes of memory. + * Allocate @p n bytes of memory. * * @param allocator the allocator * @param n the number of bytes @@ -241,12 +241,12 @@ ); /** - * Re-allocate the previously allocated block in \p mem, making the new block - * \p n bytes long. + * Re-allocate the previously allocated block in @p mem, making the new block + * @p n bytes long. * This function may return the same pointer that was passed to it, if moving * the memory was not necessary. * - * \note Re-allocating a block allocated by a different allocator is undefined. + * @note Re-allocating a block allocated by a different allocator is undefined. * * @param allocator the allocator * @param mem pointer to the previously allocated block @@ -264,16 +264,16 @@ ); /** - * Re-allocate the previously allocated block in \p mem, making the new block - * \p n bytes long. + * Re-allocate the previously allocated block in @p mem, making the new block + * @p n bytes long. * This function may return the same pointer that was passed to it, if moving * the memory was not necessary. * - * The size is calculated by multiplying \p nemb and \p size. - * If that multiplication overflows, this function returns \c NULL and \c errno + * The size is calculated by multiplying @p nemb and @p size. + * If that multiplication overflows, this function returns @c NULL and @c errno * will be set. * - * \note Re-allocating a block allocated by a different allocator is undefined. + * @note Re-allocating a block allocated by a different allocator is undefined. * * @param allocator the allocator * @param mem pointer to the previously allocated block @@ -295,17 +295,18 @@ /** * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. - * This function acts like cxRealloc() using the pointer pointed to by \p mem. + * This function acts like cxRealloc() using the pointer pointed to by @p mem. * - * \note Re-allocating a block allocated by a different allocator is undefined. + * @note Re-allocating a block allocated by a different allocator is undefined. * - * \par Error handling - * \c errno will be set, if the underlying realloc function does so. + * @par Error handling + * @c errno will be set, if the underlying realloc function does so. * * @param allocator the allocator * @param mem pointer to the pointer to allocated block * @param n the new size in bytes - * @return zero on success, non-zero on failure + * @retval zero success + * @retval non-zero failure */ cx_attr_nodiscard cx_attr_nonnull @@ -318,17 +319,18 @@ /** * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. - * This function acts like cxRealloc() using the pointer pointed to by \p mem. + * This function acts like cxRealloc() using the pointer pointed to by @p mem. * - * \note Re-allocating a block allocated by a different allocator is undefined. + * @note Re-allocating a block allocated by a different allocator is undefined. * - * \par Error handling - * \c errno will be set, if the underlying realloc function does so. + * @par Error handling + * @c errno will be set, if the underlying realloc function does so. * - * @param allocator the allocator - * @param mem pointer to the pointer to allocated block - * @param n the new size in bytes - * @return zero on success, non-zero on failure + * @param allocator (@c const @c CxAllocator*) the allocator + * @param mem (@c void**) pointer to the pointer to allocated block + * @param n (@c size_t) the new size in bytes + * @retval zero success + * @retval non-zero failure */ #define cxReallocate(allocator, mem, n) \ cxReallocate(allocator, (void**)(mem), n) @@ -337,19 +339,20 @@ * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. * This function acts like cxReallocArray() using the pointer pointed to - * by \p mem. + * by @p mem. * - * \note Re-allocating a block allocated by a different allocator is undefined. + * @note Re-allocating a block allocated by a different allocator is undefined. * - * \par Error handling - * \c errno will be set, if the underlying realloc function does so or the - * multiplication of \p nmemb and \p size overflows. + * @par Error handling + * @c errno will be set, if the underlying realloc function does so or the + * multiplication of @p nmemb and @p size overflows. * * @param allocator the allocator * @param mem pointer to the pointer to allocated block * @param nmemb the number of elements * @param size the size of each element - * @return zero on success, non-zero on failure + * @retval zero success + * @retval non-zero on failure */ cx_attr_nodiscard cx_attr_nonnull @@ -364,25 +367,26 @@ * Re-allocate a previously allocated block and changes the pointer in-place, * if necessary. * This function acts like cxReallocArray() using the pointer pointed to - * by \p mem. + * by @p mem. * - * \note Re-allocating a block allocated by a different allocator is undefined. + * @note Re-allocating a block allocated by a different allocator is undefined. * - * \par Error handling - * \c errno will be set, if the underlying realloc function does so or the - * multiplication of \p nmemb and \p size overflows. + * @par Error handling + * @c errno will be set, if the underlying realloc function does so or the + * multiplication of @p nmemb and @p size overflows. * - * @param allocator the allocator - * @param mem pointer to the pointer to allocated block - * @param nmemb the number of elements - * @param size the size of each element - * @return zero on success, non-zero on failure + * @param allocator (@c const @c CxAllocator*) the allocator + * @param mem (@c void**) pointer to the pointer to allocated block + * @param nmemb (@c size_t) the number of elements + * @param size (@c size_t) the size of each element + * @retval zero success + * @retval non-zero failure */ #define cxReallocateArray(allocator, mem, nmemb, size) \ cxReallocateArray(allocator, (void**) (mem), nmemb, size) /** - * Allocate \p nelem elements of \p n bytes each, all initialized to zero. + * Allocate @p nelem elements of @p n bytes each, all initialized to zero. * * @param allocator the allocator * @param nelem the number of elements
