From d7cb08134102b7a2410c48d2a1802193f9031e00 Mon Sep 17 00:00:00 2001
From: Kimplul <kimi.h.kuparinen@gmail.com>
Date: Sun, 29 May 2022 16:23:41 +0300
Subject: continue documentation efforts

---
 include/apos/attrs.h | 56 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 46 insertions(+), 10 deletions(-)

(limited to 'include/apos/attrs.h')

diff --git a/include/apos/attrs.h b/include/apos/attrs.h
index 3825ece..9729000 100644
--- a/include/apos/attrs.h
+++ b/include/apos/attrs.h
@@ -6,20 +6,56 @@
  * Attribute shorthands.
  */
 
-/* TODO: figure out which attributes are necessary and which are good to have */
+/**
+ * Ask the preprocessor if specified attribute is available.
+ * Currently unused, but I really should use it.
+ *
+ * @param x Attribute whose existence should be checked.
+ * @return Non-zero when available, \c 0 when not available.
+ * @todo Figure out which attributes are necessary and which are good to have
+ */
 #if !defined(__has_attribute)
 #define __has_attribute(x) 0
 #endif
 
+/**
+ * Place object into section.
+ *
+ * @param section Section name to place the object in.
+ */
 #define __section(section) __attribute__((__section__(section)))
-#define __fmt(x, y)        __attribute__((format(__printf__, x, y)))
-#define __aligned(a)       __attribute__((aligned(a)))
-#define __noinline         __attribute__((noinline))
-#define __noreturn         __attribute__((noreturn))
-#define __packed           __attribute__((packed))
-#define __weak             __attribute__((weak))
-
-#define __main             __section(".kernel.start") __noinline
-#define __init             __section(".init.start") __noinline
+
+/**
+ * Inform the compiler that the function uses printf formatting.
+ *
+ * @param x Index of the format string.
+ * @param y Index of variadic arguments.
+ */
+#define __fmt(x, y) __attribute__((format(__printf__, x, y)))
+
+/**
+ * Align object.
+ *
+ * @param a Value to which object should be aligned.
+ */
+#define __aligned(a) __attribute__((aligned(a)))
+
+/** Don't inline function. */
+#define __noinline __attribute__((noinline))
+
+/** Function should not return. */
+#define __noreturn __attribute__((noreturn))
+
+/** Pack structure. */
+#define __packed __attribute__((packed))
+
+/** Weak linkage. */
+#define __weak __attribute__((weak))
+
+/** Main entry point of kernel proper. */
+#define __main __section(".kernel.start") __noinline
+
+/** Entry point of kernel loader. */
+#define __init __section(".init.start") __noinline
 
 #endif /* APOS_COMPILER_ATTRIBUTES_H */
-- 
cgit v1.3