From 24891bf97f032b64e846ff61a67a97ea63a510ca Mon Sep 17 00:00:00 2001
From: Ronald Caesar <github43132@proton.me>
Date: Fri, 23 Jan 2026 17:58:32 -0400
Subject: [PATCH] engine: update bal_attributes.h docs formatting

Signed-off-by: Ronald Caesar <github43132@proton.me>
---
 include/bal_attributes.h | 46 +++++++++++++++-------------------------
 1 file changed, 17 insertions(+), 29 deletions(-)

diff --git a/include/bal_attributes.h b/include/bal_attributes.h
index 61debf4..6e3aeea 100644
--- a/include/bal_attributes.h
+++ b/include/bal_attributes.h
@@ -8,15 +8,12 @@
 
 #include "bal_platform.h"
 
-/*!
- * BAL_HOT()/BAL_COLD()
- * Marks a function as hot or cold. Hot makes the compiller optimize it more
- * aggressively. Cold marks the function as rarely executed.
- *
- * Usage:
- * BAL_HOT bal_error_t emit_instruction(...);
- */
-
+/// BAL_HOT()/BAL_COLD()
+/// Marks a function as hot or cold. Hot makes the compiller optimize it more
+/// aggressively. Cold marks the function as rarely executed.
+///
+/// Usage:
+/// BAL_HOT bal_error_t emit_instruction(...);
 #if BAL_COMPILER_GCC
 
 #define BAL_HOT  __attribute__((hot))
@@ -29,13 +26,10 @@
 
 #endif
 
-/*!
- * BAL_LIKELY(x)/BAL_UNLIKELY(x)
- * Hints to the CPU branch predictor. Should only be used in hot functions.
- *
- * Usage: if (BAL_UNLIKELY(ptr == NULL)) { ... }
- */
-
+/// BAL_LIKELY(x)/BAL_UNLIKELY(x)
+/// Hints to the CPU branch predictor. Should only be used in hot functions.
+///
+/// Usage: if (BAL_UNLIKELY(ptr == NULL)) { ... }
 #if BAL_COMPILER_GCC
 
 #define BAL_LIKELY(x)   __builtin_expect(!!(x), 1)
@@ -48,13 +42,10 @@
 
 #endif
 
-/*!
- * BAL_ALIGNED(x)
- * Aligns a variable or a structure to x bytes.
- *
- * Usage: BAL_ALIGNED(64)  struct data { ... };
- */
-
+/// BAL_ALIGNED(x)
+/// Aligns a variable or a structure to x bytes.
+///
+/// Usage: BAL_ALIGNED(64)  struct data { ... };
 #if BAL_COMPILER_GCC
 
 #define BAL_ALIGNED(x) __attribute__((aligned(x)))
@@ -69,12 +60,9 @@
 
 #endif
 
-/*!
- * BAL_RESTRICT:
- * Tells the compiler that a pointer does not alias any other pointer in
- * current scope.
- */
-
+/// BAL_RESTRICT
+/// Tells the compiler that a pointer does not alias any other pointer in
+/// current scope.
 #if BAL_COMPILER_GCC
 
 #define BAL_RESTRICT __restrict__