Clarification to AM_DO_ONCE(), AM_DO_EACH_MS() and AM_DO_EVERY() macros

Author: adel-mamin

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [0-based versioning](https://0ver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- Clarification to `AM_DO_ONCE()`, `AM_DO_EACH_MS()` and `AM_DO_EVERY()` macros.
+
 ## v0.14.0 - 24-August-2025
 
 ### Changed

cspell.json

@@ -128,6 +128,7 @@
         "Wcast",
         "nbusy",
         "npools",
+        "smth",
     ],
     // flagWords - list of words to be always considered incorrect
     // This is useful for offensive words and common spelling errors.

libs/common/macros.h

@@ -119,6 +119,20 @@ AM_NORETURN void am_assert_failure(
  *         ++i;
  *     }
  * }
+ *
+ * Note:
+ *
+ * The macro requires explicit curly braces, when used
+ * in the context of if, switch-case, for, while:
+ *
+ * E.g., this is correct:
+ *
+ * if (smth) { AM_DO_EVERY(2) {smth} }
+ *
+ * This is NOT correct and will not compile:
+ *
+ * if (smth) AM_DO_EVERY(2) {smth}
+ *
  * after iteration number| i
  * ----------------------+--
  *   1                   | 1
@@ -144,6 +158,19 @@ AM_NORETURN void am_assert_failure(
  *     }
  * }
  *
+ * Note:
+ *
+ * The macro requires explicit curly braces, when used
+ * in the context of if, switch-case, for, while:
+ *
+ * E.g., this is correct:
+ *
+ * if (smth) { AM_DO_ONCE() {smth} }
+ *
+ * This is NOT correct and will not compile:
+ *
+ * if (smth) AM_DO_ONCE() {smth}
+ *
  * after iteration number| i
  * ----------------------+--
  *   1                   | 1
@@ -158,6 +185,19 @@ AM_NORETURN void am_assert_failure(
  * Execute code in the attached scope immediately and
  * then repeatedly every \p ms milliseconds.
  *
+ * Note:
+ *
+ * The macro requires explicit curly braces, when used
+ * in the context of if, switch-case, for, while:
+ *
+ * E.g., this is correct:
+ *
+ * if (smth) { AM_DO_EACH_MS(5) {smth} }
+ *
+ * This is NOT correct and will not compile:
+ *
+ * if (smth) AM_DO_EACH_MS(5) {smth}
+ *
  * Example:
  * AM_DO_EACH_MS(100) {
  *     am_pal_printf("Hello, world!\n");