From d5d5e9f602c75ba8f30ff46ef0ce8212a4fa07c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mikolai=20G=C3=BCtschow?= <mikolai.guetschow@tu-dresden.de>
Date: Mon, 27 May 2024 17:11:54 +0200
Subject: [PATCH] core/lib/assert: consistify output and cleanup documentation

---
 core/lib/assert.c         |  6 ++----
 core/lib/include/assert.h | 31 +++++++++++++++----------------
 2 files changed, 17 insertions(+), 20 deletions(-)

diff --git a/core/lib/assert.c b/core/lib/assert.c
index 73558e8cf9..fd28111e32 100644
--- a/core/lib/assert.c
+++ b/core/lib/assert.c
@@ -28,9 +28,7 @@
 __NORETURN static inline void _assert_common(void)
 {
 #if IS_USED(MODULE_BACKTRACE)
-#ifdef DEBUG_ASSERT_VERBOSE
-    printf("failed assertion. Backtrace:\n");
-#endif
+    printf("FAILED ASSERTION. Backtrace:\n");
     backtrace_print();
 #endif
 #ifdef DEBUG_ASSERT_BREAKPOINT
@@ -53,7 +51,7 @@ __NORETURN void _assert_failure(const char *file, unsigned line)
 
 __NORETURN void _assert_panic(void)
 {
-    printf("%" PRIxTXTPTR "\n", cpu_get_caller_pc());
+    printf("0x%" PRIxTXTPTR " => ", cpu_get_caller_pc());
     _assert_common();
 }
 
diff --git a/core/lib/include/assert.h b/core/lib/include/assert.h
index 665813c92c..322926cae1 100644
--- a/core/lib/include/assert.h
+++ b/core/lib/include/assert.h
@@ -32,10 +32,12 @@ extern "C" {
 /**
  * @brief   Activate verbose output for @ref assert() when defined.
  *
- * Without this macro defined the @ref assert() macro will just print the
- * address of the code line the assertion failed in. With the macro defined
- * the macro will also print the file, the code line and the function this macro
- * failed in.
+ * Without this macro defined, @ref assert() will just print the address of the
+ * code line the assertion failed in. With this macro defined, @ref assert()
+ * will also print the file and the code line of the failed assertion.
+ *
+ * Enabling verbose output will on the other hand lead to an increased size of
+ * the binary, since it needs to contain the names of all files with assertions.
  *
  * To define just add it to your `CFLAGS` in your application's Makefile:
  *
@@ -49,7 +51,7 @@ extern "C" {
  * @brief   Activate breakpoints for @ref assert() when defined
  *
  * Without this macro defined the @ref assert() macro will just print some
- * information about the failed assertion, see @ref assert and
+ * information about the failed assertion, see @ref assert() and
  * @ref DEBUG_ASSERT_VERBOSE.
  * If @ref DEBUG_ASSERT_BREAKPOINT is defined, the execution will stop on a
  * failed assertion instead of producing the output. If the architecture
@@ -106,24 +108,21 @@ __NORETURN void _assert_failure(const char *file, unsigned line);
  * The purpose of this macro is to help programmers find bugs in their
  * programs.
  *
- * With @ref DEBUG_ASSERT_VERBOSE defined this will print also the file, the
- * line and the function this assertion failed in.
+ * A failed assertion generates output similar to:
  *
- * If `NDEBUG` and @ref DEBUG_ASSERT_VERBOSE are not defined, a failed assertion
- * generates output similar to:
- *
- *     0x89abcdef
- *     *** RIOT kernel panic:
- *     FAILED ASSERTION.
- *
- *     ...
+ *     0x89abcdef => FAILED ASSERTION.
  *
  * Where 0x89abcdef is an address. This address can be used with tools like
  * `addr2line` (or e.g. `arm-none-eabi-addr2line` for ARM-based code), `objdump`,
  * or `gdb` (with the command `info line *(0x89abcdef)`) to identify the line
  * the assertion failed in.
  *
- * If the `backtrace` module is enabled (and implemented for architecture in use)
+ * With @ref DEBUG_ASSERT_VERBOSE defined this will instead directly print the
+ * file and the line the assertion failed in:
+ *
+ *     example/file.c:42 => FAILED ASSERTION.
+ *
+ * If the `backtrace` module is enabled (and implemented for the architecture in use)
  * a backtrace will be printed in addition to the location of the failed assertion.
  *
  * If @ref DEBUG_ASSERT_BREAKPOINT is defined, the execution will stop on a