diff --git a/libc/inc/stddef.h b/libc/inc/stddef.h
index 5e89e7a..6eb5b2f 100644
--- a/libc/inc/stddef.h
+++ b/libc/inc/stddef.h
@@ -72,6 +72,13 @@ typedef unsigned int pgprot_t;
 /// Counts the number of elements of an array.
 #define count_of(x) ((sizeof(x) / sizeof((x)[0])) / ((size_t)(!(sizeof(x) % sizeof((x)[0])))))
 
+/// @brief Swaps two values.
+/// @details
+/// do { ... } while (0) allows to place multistatement operations, for
+/// instance, inside the following if stantement:
+/// if (condition)
+///     swap(var1, var2)
+/// which otherwise would be wrong.
 #define swap(a, b)             \
     do {                       \
         typeof(a) temp = (a);  \