From 3f975a07213f8769477e13dbb9b70e9932f60f60 Mon Sep 17 00:00:00 2001
From: zenon <kranklyboy1000@gmail.com>
Date: Sat, 9 Jun 2018 12:58:24 +0200
Subject: [PATCH] Add comments for documentation to each function

---
 supervisor.c | 75 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 72 insertions(+), 3 deletions(-)

diff --git a/supervisor.c b/supervisor.c
index 0a4cb4f..4b266b9 100644
--- a/supervisor.c
+++ b/supervisor.c
@@ -8,29 +8,66 @@
 #include "common.h"
 #include <limits.h>
 
+/**
+ * @details Global variable for the program name.
+ */
 static const char *pname;
 
+/**
+ * @details Struct for shared memory.
+ */
 struct circ_buf *shared;
 
+/**
+ * @details File descriptor for shared memory.
+ */
 int shmfd;
 
+/**
+ * @details Semaphore which counts the used space in the shared memory array.
+ */
 static sem_t *sUsedSpace;
 
+/**
+ * @details Semaphore which counts the free space in the shared memory array.
+ */
 static sem_t *sFreeSpace;
 
+/**
+ * @details Semaphore to ensure exclusive access to shared memory from generators.
+ */
 static sem_t *sWriteEnd;
 
+/**
+ * @details Struct for signal handling.
+ */
 struct sigaction sa;
 
+/**
+ * @details Array which remembers the best solution so far.
+ */
 static int bestSolution[MAX_ITEMS];
 
+/**
+ * @details Variable which gets set on signal received.
+ */
 static volatile sig_atomic_t quit = 0;
 
+/**
+ * @details Signal handler.
+ * @param signal The number of the received signal.
+ * @return This function has no return value.
+ */
 static void sig_handler(int signum)
 {
 	quit = 1;
 }
 
+/**
+ * @details Prints the synopsis.
+ * @param void This function takes no parameters.
+ * @return Always non-zero.
+ */
 void usage(void)
 {
 	fprintf(stderr, "SYNOPSIS\n"
@@ -38,7 +75,13 @@ void usage(void)
 	exit(EXIT_FAILURE);
 }
 
-void cleanup()
+/**
+ * @details Cleanup function which sets the quit variable in shared memory to 1
+ *          and closes shared memory and semaphores.
+ * @param void This function takes no parameters.
+ * @return 0 on success, non-zero on failure.
+ */
+void cleanup(void)
 {
 	shared->quit = 1;
 	sem_wait(sUsedSpace);
@@ -65,7 +108,13 @@ void cleanup()
 	exit(EXIT_SUCCESS);
 }
 
-void initCircBuf()
+/**
+ * @details Function which initializes the shared memory buffer and sets the
+ *          initial bestSolution to INT_MAX.
+ * @param void This function takes no parameters.
+ * @return This function has no return value.
+ */
+void initCircBuf(void)
 {
 	shared->quit = 0;
 	for (int i = 0; i < MAX_ITEMS; i++) {
@@ -75,9 +124,13 @@ void initCircBuf()
 	for (int i = 0; i < MAX_ITEMS; i++) {
 		bestSolution[i] = INT_MAX;
 	}
-	return;
 }
 
+/**
+ * @details Custom function for sem_wait which also listens for signals.
+ * @param sem The semaphore to be decremented.
+ * @return 0 on success, non-zero on failure.
+ */
 void wait_sem(sem_t *sem)
 {
 	while (sem_wait(sem) == -1) { // interrupted by syscall? 
@@ -94,6 +147,13 @@ void wait_sem(sem_t *sem)
 	return;
 }
 
+/**
+ * @details Function which reads a solution from the circular buffer and compares
+ *          it to the current bestSolution. If smaller, replace bestSolution.
+ * @param sUsedSpace Semaphore which counts the used space.
+ * @param sFreeSpace Semaphore which counts the free space.
+ * @return This function has no return value.
+ */ 
 void getSolution(sem_t *sUsedSpace, sem_t *sFreeSpace)
 {
 	int solution[MAX_ITEMS];
@@ -157,6 +217,15 @@ void getSolution(sem_t *sUsedSpace, sem_t *sFreeSpace)
 	}
 }
 
+/**
+ * The main entry point of the program.
+ * @details Sets the signal handler, sets up shared memory and semaphores and
+ *          initializes the shared memory buffer. Loops until solution with 0
+ *          edges found or signal received.
+ * @param argc The number of supplied commandline arguments.
+ * @param argv The array of supplied commandline arguments.
+ * @return 0 on success, non-zero on failre.
+ */
 int main(int argc, char *argv[])
 {
 	if (argc != 1)