From ce09eafdd23a23f1b6389cd2536dd73a6642196b Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Mon, 17 Nov 2025 16:11:35 -0500
Subject: Document semaphore usage

---
 src/lib/core/include/sem.h | 41 ++++++++++++++++++++++++++++++++++++++++-
 src/lib/core/semaphore.c   |  3 +++
 2 files changed, 43 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/lib/core/include/sem.h b/src/lib/core/include/sem.h
index 868f33d..947f9e8 100644
--- a/src/lib/core/include/sem.h
+++ b/src/lib/core/include/sem.h
@@ -1,13 +1,52 @@
+/**
+* @file sem.h
+*/
 #ifndef STASIS_SEMAPHORE_H
 #define STASIS_SEMAPHORE_H
 
+#include "core.h"
 #include <semaphore.h>
 
 struct Semaphore {
     sem_t *sem;
-    char name[255];
+    char name[STASIS_NAME_MAX];
 };
 
+/**
+ * Initialize a cross-platform semaphore (Linux/Darwin)
+ *
+ * @code c
+ * #include "sem.h"
+ *
+ * int main(int argc, char *argv[]) {
+ *     struct Semaphore s;
+ *     if (semaphore_init(&s, "mysem", 1)) {
+ *         perror("semaphore_init failed");
+ *         exit(1);
+ *     }
+ *     if (semaphore_wait(&s)) {
+ *         perror("semaphore_wait failed");
+ *         exit(1);
+ *     }
+ *
+ *     //
+ *     // Critical section
+ *     // CODE HERE
+ *     //
+ *
+ *     if (semaphore_post(&s)) {
+ *         perror("semaphore_post failed");
+ *         exit(1);
+ *     }
+ * }
+ * @endcode
+ *
+ * @param s a pointer to `Semaphore`
+ * @param name of the semaphore
+ * @param value initial value of the semaphore
+ * @return -1 on error
+ * @return 0 on success
+ */
 int semaphore_init(struct Semaphore *s, const char *name, int value);
 int semaphore_wait(struct Semaphore *s);
 int semaphore_post(struct Semaphore *s);
diff --git a/src/lib/core/semaphore.c b/src/lib/core/semaphore.c
index a884469..60a928a 100644
--- a/src/lib/core/semaphore.c
+++ b/src/lib/core/semaphore.c
@@ -1,3 +1,6 @@
+/**
+* @file semaphore.c
+*/
 #include <stdio.h>
 #include <fcntl.h>
 
-- 
cgit