diff --git a/src/common/pico_base_headers/include/pico/assert.h b/src/common/pico_base_headers/include/pico/assert.h
index 36e25efae..cc33779a4 100644
--- a/src/common/pico_base_headers/include/pico/assert.h
+++ b/src/common/pico_base_headers/include/pico/assert.h
@@ -38,6 +38,16 @@ extern "C" {
 
 #ifdef NDEBUG
 extern void hard_assertion_failure(void);
+
+/*! \brief  Perform a runtime assertion always (i.e. not just when NDEBUG is undefined)
+*  \ingroup pico_base
+*
+* This function is intended to provide useful information in debug builds like a normal assertion, but also
+* prevent execution proceeding in other builds
+*
+* In debug builds this is equivalent to \ref assert, however in release builds it calls \ref hard_assertion_failure
+* which, by default, just calls \ref panic with the string "Hard assert"
+*/
 static inline void hard_assert(bool condition, ...) {
     if (!condition)
         hard_assertion_failure();
diff --git a/src/rp2_common/pico_runtime/runtime.c b/src/rp2_common/pico_runtime/runtime.c
index 42452e5bb..d8bae8900 100644
--- a/src/rp2_common/pico_runtime/runtime.c
+++ b/src/rp2_common/pico_runtime/runtime.c
@@ -8,6 +8,15 @@
 #include "pico/runtime_init.h"
 
 
+/*! \brief  Handle a hard_assert condition failure
+*  \ingroup pico_runtime
+*
+* This weak function provides the default implementation (call \ref panic with "Hard assert") for if a \ref hard_assert
+* condition fail in non debug builds. You can provide your own strong implementation to replace the default behavior
+*
+* \sa hard_assert
+*/
+
 void __weak hard_assertion_failure(void) {
     panic("Hard assert");
 }