Improve doxygen documentation by hiding internal symbols

src/overture/cli.h

@@ -47,11 +47,24 @@ struct cli_option {
     enum cli_state (*parse)(void*, char*);
 };
 
-/// Internal command-line parser boolean callback.
+/// @cond PRIVATE
 static inline enum cli_state cli_set_flag(void* data, char*) {
     return *(bool*)data = true, CLI_STATE_ACCEPTED;
 }
 
+static inline enum cli_state cli_set_uint32(void* data, char* arg) {
+    return *(uint32_t*)data = strtoul(arg, NULL, 10), CLI_STATE_ACCEPTED;
+}
+
+static inline enum cli_state cli_set_uint64(void* data, char* arg) {
+    return *(uint64_t*)data = strtoumax(arg, NULL, 10), CLI_STATE_ACCEPTED;
+}
+
+static inline enum cli_state cli_set_string(void* data, char* arg) {
+    return *(char**)data = arg, CLI_STATE_ACCEPTED;
+}
+/// @endcond
+
 /// Produces a boolean flag with no arguments.
 [[nodiscard]] static inline struct cli_option cli_flag(
     const char* short_name,
@@ -66,11 +79,6 @@ static inline enum cli_state cli_set_flag(void* data, char*) {
     };
 }
 
-/// Internal command-line parser 32-bit integer callback.
-static inline enum cli_state cli_set_uint32(void* data, char* arg) {
-    return *(uint32_t*)data = strtoul(arg, NULL, 10), CLI_STATE_ACCEPTED;
-}
-
 /// Produces an option that takes a 32-bit unsigned integer as an argument.
 [[nodiscard]] static inline struct cli_option cli_option_uint32(
     const char* short_name,
@@ -86,11 +94,6 @@ static inline enum cli_state cli_set_uint32(void* data, char* arg) {
     };
 }
 
-/// Internal command-line parser 64-bit integer callback.
-static inline enum cli_state cli_set_uint64(void* data, char* arg) {
-    return *(uint64_t*)data = strtoumax(arg, NULL, 10), CLI_STATE_ACCEPTED;
-}
-
 /// Produces an option that takes a 64-bit unsigned integer as an argument.
 [[nodiscard]] static inline struct cli_option cli_option_uint64(
     const char* short_name,
@@ -106,11 +109,6 @@ static inline enum cli_state cli_set_uint64(void* data, char* arg) {
     };
 }
 
-/// Internal command-line parser string callback.
-static inline enum cli_state cli_set_string(void* data, char* arg) {
-    return *(char**)data = arg, CLI_STATE_ACCEPTED;
-}
-
 /// Produces an option that takes a string as an argument.
 [[nodiscard]] static inline struct cli_option cli_option_string(
     const char* short_name,

src/overture/hash_table.h

@@ -23,8 +23,10 @@ struct hash_table {
     char* vals;         ///< Hash table values. May be `NULL`.
 };
 
+/// @cond PRIVATE
 #define HASH_TABLE_OCCUPIED_FLAG UINT32_C(0x80000000)
 #define HASH_TABLE_MAX_LOAD_FACTOR 70 //%
+/// @endcond
 
 /// Creates a hash table.
 /// @param key_size Size of a key (in bytes)

src/overture/immutable_set.h

@@ -12,8 +12,10 @@
 /// Immutable set data structure. Immutable sets are represented as sorted arrays, that
 /// are placed in a set data structure, ensuring that there are unique.
 
+/// @cond PRIVATE
 #define IMMUTABLE_SET_POOL_DEFAULT_CAPACITY 4
 #define IMMUTABLE_SET_SMALL_CAPACITY 4
+/// @endcond
 
 /// Iterates over the elements of an immutable set.
 /// @param elem_ty Type of the elements in the immutable set.

src/overture/map.h

@@ -11,6 +11,7 @@
 /// Hash map data structure providing fast insertion, search, and removal.
 /// @see hash_table.
 
+/// @cond PRIVATE
 #define MAP_DEFAULT_CAPACITY 4
 #define MAP_PREFIX map_very_long_prefix_
 
@@ -22,6 +23,7 @@
 
 #define MAP_FOREACH_ACCESS(ty, val, elems) \
     for (ty const* val = &((ty const*)(elems))[MAP_PREFIX##i]; MAP_PREFIX##once; MAP_PREFIX##once = false) \
+/// @endcond
 
 /// Iterates over the keys and values of a map.
 /// @param key_ty Type of the keys in the hash map.
@@ -70,6 +72,7 @@
     VISIBILITY(vis) void name##_destroy(struct name*); \
     VISIBILITY(vis) void name##_clear(struct name*); \
     VISIBILITY(vis) bool name##_insert(struct name*, key_ty const*, val_ty const*); \
+    [[nodiscard]] VISIBILITY(vis) bool name##_is_empty(const struct name*); \
     VISIBILITY(vis) val_ty const* name##_find(const struct name*, key_ty const*); \
     VISIBILITY(vis) bool name##_remove(struct name*, key_ty const*);
 
@@ -102,6 +105,9 @@
         } \
         return false; \
     } \
+    VISIBILITY(vis) bool name##_is_empty(const struct name* map) { \
+        return map->elem_count == 0; \
+    } \
     VISIBILITY(vis) val_ty const* name##_find(const struct name* map, key_ty const* key) { \
         size_t idx; \
         if (!hash_table_find(&map->hash_table, &idx, key, sizeof(key_ty), hash(hash_init(), key), name##_is_equal_wrapper)) \

src/overture/queue.h

@@ -32,7 +32,7 @@
     [[nodiscard]] VISIBILITY(vis) struct name name##_create(void); \
     VISIBILITY(vis) void name##_destroy(struct name*); \
     VISIBILITY(vis) elem_ty const* name##_top(const struct name*); \
-    VISIBILITY(vis) bool name##_is_empty(const struct name*); \
+    [[nodiscard]] VISIBILITY(vis) bool name##_is_empty(const struct name*); \
     VISIBILITY(vis) void name##_push(struct name*, elem_ty const*); \
     VISIBILITY(vis) void name##_pop(struct name*); \
     VISIBILITY(vis) void name##_clear(struct name*);

src/overture/set.h

@@ -11,8 +11,10 @@
 /// Hash set data structure providing fast insertion, search, and removal.
 /// @see hash_table.
 
+/// @cond PRIVATE
 #define SET_DEFAULT_CAPACITY 4
 #define SET_PREFIX set_very_long_prefix_
+/// @endcond
 
 /// Iterates over the elements of a hash set.
 /// @param elem_ty Type of the elements in the hash set.
@@ -47,6 +49,7 @@
     VISIBILITY(vis) void name##_destroy(struct name*); \
     VISIBILITY(vis) void name##_clear(struct name*); \
     VISIBILITY(vis) bool name##_insert(struct name*, elem_ty const*); \
+    [[nodiscard]] VISIBILITY(vis) bool name##_is_empty(const struct name*); \
     VISIBILITY(vis) elem_ty const* name##_find(const struct name*, elem_ty const*); \
     VISIBILITY(vis) bool name##_remove(struct name*, elem_ty const*);
 
@@ -79,6 +82,9 @@
         } \
         return false; \
     } \
+    VISIBILITY(vis) bool name##_is_empty(const struct name* set) { \
+        return set->elem_count == 0; \
+    } \
     VISIBILITY(vis) elem_ty const* name##_find(const struct name* set, elem_ty const* elem) { \
         size_t idx; \
         if (!hash_table_find(&set->hash_table, &idx, elem, sizeof(elem_ty), hash(hash_init(), elem), name##_is_equal_wrapper)) \

src/overture/str.h

@@ -19,13 +19,13 @@
 /// Constructs a string view from the given C string.
 #define STR_VIEW(x) ((struct str_view) { .data = (x), .length = strlen((x)) })
 
-/// View into a character string. May or may not be `NULL`-terminated.
+/// View into a character string. May or may not be zero-terminated.
 struct str_view {
     const char* data;
     size_t length;
 };
 
-/// Dynamically-allocated string. May or may not be `NULL`-terminated.
+/// Dynamically-allocated string. May or may not be zero-terminated.
 struct str {
     char* data;
     size_t length;
@@ -64,6 +64,13 @@ struct str {
     };
 }
 
+[[nodiscard]] static inline struct str_view str_to_view(const struct str* str) {
+    return (struct str_view) {
+        .data = str->data,
+        .length = str->length
+    };
+}
+
 static inline void str_grow(struct str* str, size_t added_bytes) {
     if (str->length + added_bytes > str->capacity) {
         str->capacity += str->capacity >> 1;
@@ -92,7 +99,8 @@ static inline void str_destroy(struct str* str) {
     free(str->data);
 }
 
-/// Makes sure the given string is `NULL`-terminated. Returns a valid C-string that points to it.
+/// Makes sure the given string is zero-terminated. Returns a valid C-string that points to it.
+/// This function can be called several times, and will only append a terminator character once.
 static inline const char* str_terminate(struct str* str) {
     if (str->length == 0 || str->data[str->length - 1] != 0)
         str_push(str, '\0');

src/overture/test.c

@@ -106,9 +106,12 @@ static bool summarize_tests(bool disable_colors) {
         disable_colors ? "" : color_code(failed == 0),
         passed_tests, enabled_tests, passed_asserts,
         disable_colors ? "" : TERM1(TERM_RESET));
+    return !failed;
+}
+
+void cleanup_tests(void) {
     test_vec_destroy(&tests);
     memset(&tests, 0, sizeof(struct test_vec));
-    return !failed;
 }
 
 static inline void print_failed_assert(
@@ -120,7 +123,7 @@ static inline void print_failed_assert(
     fprintf(stderr, "[%s] Assertion '%s' failed (%s:%u)\n", context->test->name, msg, file, line);
 }
 
-void print_test_names(FILE* file) {
+void print_tests(FILE* file) {
     VEC_FOREACH(struct test, test, tests)
         fprintf(file, "%s\n", test->name);
 }

src/overture/test.h

@@ -4,8 +4,8 @@
 
 /// @file
 ///
-/// Test framework for C programs. Supports process isolation on POSIX platforms. With this
-/// framework, tests can be written with very little code:
+/// Test framework for C programs. This test framework supports process isolation on POSIX
+/// platforms. With it, very little code is required to write tests:
 ///
 /// ```c
 /// TEST(my_test) {
@@ -44,11 +44,13 @@
             require_success(context); \
     } while (false)
 
+/// @cond PRIVATE
 struct test_context;
+/// @endcond
 
 /// Run all the enabled tests, and then print the result on the standard output. This function can
 /// only be called once.
-/// @return `true` on success, `false` otherwise.
+/// @return `true` if all tests pass, `false` otherwise.
 bool run_tests(bool disable_colors);
 
 /// Filters tests based on the names that appear in the given list of arguments.
@@ -58,14 +60,14 @@ bool run_tests(bool disable_colors);
 /// @param argv Prefixes to use for matching.
 void filter_tests(int argc, char** argv);
 
+/// Cleanup the memory associated with the tests.
+void cleanup_tests(void);
+
 /// Prints available test names, separated by new lines, on the given stream.
-void print_test_names(FILE*);
+void print_tests(FILE*);
 
-/// Internal function called by the framework when a requirement fails. Do not call directly.
+/// @cond PRIVATE
 [[noreturn]] void require_fail(struct test_context*, const char*, const char*, unsigned);
-
-/// Internal function called by the framework when a requirement succeeds. Do not call directly.
 void require_success(struct test_context*);
-
-/// Internal function to register a test. Do not call directly.
 void register_test(const char*, void (*) (struct test_context*));
+/// @endcond

src/overture/thread_pool.h

@@ -18,13 +18,13 @@ struct work_item {
 
 /// Creates a new thread pool with an empty queue.
 /// @param thread_count Number of threads to create in the pool, or 0 to autodetect the number of cores.
-struct thread_pool* thread_pool_create(size_t thread_count);
+[[nodiscard]] struct thread_pool* thread_pool_create(size_t thread_count);
 
 /// Destroys the thread pool, and terminates the worker threads, without waiting for completion.
 void thread_pool_destroy(struct thread_pool* thread_pool);
 
 /// @return The number of worker threads contained in the given pool.
-size_t thread_pool_size(const struct thread_pool* thread_pool);
+[[nodiscard]] size_t thread_pool_size(const struct thread_pool* thread_pool);
 
 /// Enqueues several work items in order on a thread pool, using locks to prevent data races.
 void thread_pool_submit(

src/overture/unique_stack.h

@@ -31,7 +31,7 @@
     [[nodiscard]] VISIBILITY(vis) struct name name##_create(void); \
     VISIBILITY(vis) void name##_destroy(struct name*); \
     VISIBILITY(vis) bool name##_push(struct name*, elem_ty const*); \
-    VISIBILITY(vis) bool name##_is_empty(const struct name*); \
+    [[nodiscard]] VISIBILITY(vis) bool name##_is_empty(const struct name*); \
     VISIBILITY(vis) elem_ty* name##_pop(struct name*); \
     VISIBILITY(vis) elem_ty* name##_last(struct name*); \
     VISIBILITY(vis) void name##_clear(struct name*);

src/overture/vec.h

@@ -12,7 +12,9 @@
 /// are stored on the stack when they are small enough, and are moved on the heap when they become
 /// too big.
 
+/// @cond PRIVATE
 #define SMALL_VEC_CAPACITY 4
+/// @endcond
 
 /// Iterates over the elements of a vector or small vector.
 /// @param elem_ty Type of the elements of the vector.
@@ -48,7 +50,7 @@
     VISIBILITY(vis) void name##_destroy(struct name*); \
     VISIBILITY(vis) void name##_resize(struct name*, size_t); \
     VISIBILITY(vis) void name##_push(struct name*, elem_ty const*); \
-    VISIBILITY(vis) bool name##_is_empty(const struct name*); \
+    [[nodiscard]] VISIBILITY(vis) bool name##_is_empty(const struct name*); \
     VISIBILITY(vis) elem_ty* name##_pop(struct name*); \
     VISIBILITY(vis) elem_ty* name##_last(struct name*); \
     VISIBILITY(vis) void name##_clear(struct name*);
@@ -115,6 +117,7 @@
     VISIBILITY(vis) void name##_destroy(struct name*); \
     VISIBILITY(vis) void name##_resize(struct name*, size_t); \
     VISIBILITY(vis) void name##_push(struct name*, elem_ty const*); \
+    [[nodiscard]] VISIBILITY(vis) bool name##_is_empty(const struct name*); \
     VISIBILITY(vis) elem_ty* name##_pop(struct name*); \
     VISIBILITY(vis) elem_ty* name##_last(struct name*); \
     VISIBILITY(vis) void name##_clear(struct name*);
@@ -151,6 +154,9 @@
         name##_resize(vec, vec->elem_count + 1); \
         vec->elems[vec->elem_count - 1] = *elem; \
     } \
+    VISIBILITY(vis) bool name##_is_empty(const struct name* vec) { \
+        return vec->elem_count == 0; \
+    } \
     VISIBILITY(vis) elem_ty* name##_pop(struct name* vec) { \
         return &vec->elems[--vec->elem_count]; \
     } \

src/overture/visibility.h

@@ -20,5 +20,7 @@
 /// @param vis Visibility of the symbol, which can be either `PUBLIC` or `PRIVATE`.
 #define VISIBILITY(vis) vis##_VISIBILITY
 
+/// @cond PRIVATE
 #define PUBLIC_VISIBILITY
 #define PRIVATE_VISIBILITY static inline
+/// @endcond

test/main.c

@@ -18,21 +18,23 @@ static enum cli_state usage(void*, char*) {
     return CLI_STATE_ERROR;
 }
 
-static enum cli_state print_tests(void*, char*) {
-    print_test_names(stdout);
+static enum cli_state list_tests(void*, char*) {
+    print_tests(stdout);
     return CLI_STATE_ERROR;
 }
 
 int main(int argc, char** argv) {
     struct options options = { .disable_colors = !is_term(stdout) };
     struct cli_option cli_options[] = {
         { .short_name = "-h", .long_name = "--help", .parse = usage },
-        { .long_name = "--list", .parse = print_tests },
+        { .long_name = "--list", .parse = list_tests },
         cli_flag(NULL, "--no-color", &options.disable_colors),
     };
     if (!cli_parse_options(argc, argv, cli_options, sizeof(cli_options) / sizeof(cli_options[0])))
         return 1;
 
     filter_tests(argc, argv);
-    return run_tests(options.disable_colors) ? 0 : 1;
+    int status = run_tests(options.disable_colors) ? 0 : 1;
+    cleanup_tests();
+    return status;
 }