From 23f3bdb7226f747c4026eb59ff8c4cbf9714c8f8 Mon Sep 17 00:00:00 2001 From: Neil Date: Sun, 21 Mar 2021 14:50:30 -0700 Subject: [PATCH] Documentation. --- src/min_array.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/min_array.h b/src/min_array.h index d437781..81301e7 100644 --- a/src/min_array.h +++ b/src/min_array.h @@ -47,10 +47,11 @@ static int name##_array_reserve(struct name##_array *const a, \ a->data = data, a->capacity = c0; \ return 1; \ } \ -/** Adds at least `buffer` un-initialised and uncounted elements at the back of - `a`. @return A pointer to the start of `buffer` elements, namely - `data + size`. If `a` is idle and `buffer` is zero, a null pointer is - returned, otherwise this indicates an error. @throws[realloc, ERANGE] */ \ +/** Makes sure that there are at least `buffer` contiguous, un-initialised, + elements at the back of `a`. + @return A pointer to the start of `buffer` elements, namely `a.data + a.size`. + If `a` is idle and `buffer` is zero, a null pointer is returned, otherwise + null indicates an error and `errno` will be set. @throws[realloc, ERANGE] */ \ static type *name##_array_buffer(struct name##_array *const a, \ const size_t buffer) { \ assert(a); \ @@ -59,8 +60,8 @@ static type *name##_array_buffer(struct name##_array *const a, \ if(!name##_array_reserve(a, a->size + buffer)) return 0; \ return a->data ? a->data + a->size : 0; \ } \ -/** Emplaces `n` elements on `a`. `n` must be smaller than or equal to the - highest remaining _array_buffer>. */ \ +/** Adds `n` to the size of `a`; `n` must be smaller than or equal to the + highest remaining buffer value set by _array_buffer>. */ \ static void name##_array_emplace(struct name##_array *const a, \ const size_t n) { \ assert(a && a->capacity >= a->size && n <= a->capacity - a->size); \