Add comments for functions and make functions static

generator.c

@@ -8,44 +8,92 @@
 #include "common.h"
 #include <time.h>
 
+/**
+ * @details Global variable for the program name.
+ */
 static const char *pname;
 
+/**
+ * @details Global struct for shared memory.
+ */
 static struct circ_buf *shared;
 
-int shmfd;
+/**
+ * @details Global file descriptor for shared memory.
+ */
+static int shmfd;
 
+/**
+ * @details Semaphore for tracking the used space in shared memory.
+ */
 static sem_t *sUsedSpace;
 
+/**
+ * @details Semaphore for tracking the free space in shared memory.
+ */
 static sem_t *sFreeSpace;
 
+/**
+ * @details Semaphore for exclusive access to shared memory for generators.
+ */
 static sem_t *sWriteEnd;
 
-struct sigaction sa;
+/**
+ * @details Struct for signal handler.
+ */
+static struct sigaction sa;
 
+/**
+ * @details struct which stores a node in an adjacency list.
+ */
 struct AdjListNode {
 	int dest;
 	struct AdjListNode *next;
 };
 
+/**
+ * @details Struct which respresents an adjacency list. Stores a pointer to
+ *          the first element.
+ */
 struct AdjList {
 	struct AdjListNode *head;
 };
 
+/**
+ * @details Struct which stores a graph made up of the count of nodes and an
+ *          array for the adjacency lists.
+ */
 struct Graph {
 	int V;
 	struct AdjList *array;
 };
 
-static struct Graph graph;
+/**
+ * @details Global graph which gets populated by parse().
+ */
+struct Graph graph;
 
+/**
+ * @details Variable which gets set on signal received.
+ */
 static volatile sig_atomic_t quit = 0;
 
+/**
+ * @details Signal handler.
+ * @param signum The number of the received signal.
+ * @return This function has no return value.
+ */
 static void sig_handler(int signum)
 {
 	quit = 1;
 }
 
-void usage(void)
+/**
+ * @details Prints the synopsis.
+ * @param void This function takes no parameters.
+ * @return Always non-zero.
+ */
+static void usage(void)
 {
 	fprintf(stderr, "SYNOPSIS\n"
 			"\tgenerator EDGE1...\n"
@@ -54,7 +102,12 @@ void usage(void)
 	exit(EXIT_FAILURE);
 }
 
-struct AdjListNode *newAdjListNode(int dest)
+/**
+ * @details Function which creates a new adjacency list node.
+ * @param dest The value of the node.
+ * @return Returns the new node.
+ */
+static struct AdjListNode *newAdjListNode(int dest)
 {
 	struct AdjListNode *newNode = malloc(sizeof(struct AdjListNode));
 	newNode->dest = dest;
@@ -62,7 +115,12 @@ struct AdjListNode *newAdjListNode(int dest)
 	return newNode;
 }
 
-void createGraph(int V)
+/**
+ * @details Function which creates a new graph.
+ * @param V The number of nodes in the new graph.
+ * @return This function has no return value.
+ */
+static void createGraph(int V)
 {
 	graph.V = V;
 
@@ -72,14 +130,26 @@ void createGraph(int V)
 		graph.array[i].head = NULL;
 }
 
-void addEdge(int src, int dest)
+/**
+ * @details This function adds a new edge from src to dest.
+ * @param src The source node of the edge.
+ * @param dest The destination node of the edge.
+ * @return This function has no return value.
+ */
+static void addEdge(int src, int dest)
 {
 	struct AdjListNode *newNode = newAdjListNode(dest);
 	newNode->next = graph.array[src].head;
 	graph.array[src].head = newNode;
 }
 
-int strToInt(char *str)
+/**
+ * @details Function which safely converts a string to an integer.
+ * @param str The string to be converted.
+ * @return -2 if out of range (long). -1 if out of range (int). Converted value
+ *         on success.
+ */
+static int strToInt(char *str)
 {
 	char *endptr;
 	long val;
@@ -99,7 +169,13 @@ int strToInt(char *str)
 	return (int) val;
 }
 
-void parse(int argc, char *argv[])
+/**
+ * @details Function which parses the commandline arguments and populates the graph.
+ * @param argc The number of supplied commandline arguments.
+ * @param argv The array of supplied commandline arguments.
+ * @return This function has no return value.
+ */
+static void parse(int argc, char *argv[])
 {
 	char *token;
 	int V = 0;
@@ -165,20 +241,13 @@ void parse(int argc, char *argv[])
 	}
 }
 
-void printGraph()
+/**
-{
+ * @details Cleanup function which frees memory and closes shared memory and
-	for (int v = 0; v < graph.V; v++) {
+ *          semaphores.
-		struct AdjListNode* pCrawl = graph.array[v].head;
+ * @param void This function takes no parameters.
-		printf("\n Adjacency list of vertex %d\n head ", v);
+ * @return 0 on success, non-zero on failure.
-		while (pCrawl) {
+ */
-			printf("-> %d", pCrawl->dest);
+static void cleanup(void)
-			pCrawl = pCrawl->next;
-		}
-		printf("\n");
-	}
-}
-
-void cleanup()
 {
 	sem_post(sWriteEnd);
 	sem_post(sFreeSpace);
@@ -207,8 +276,12 @@ void cleanup()
 	exit(EXIT_SUCCESS);
 }
 
-
+/**
-void wait_sem(sem_t *sem)
+ * @details Custom sem_wait function which listens for signals.
+ * @param sem Semaphore to be decremented.
+ * @return This function has no return value.
+ */
+static void wait_sem(sem_t *sem)
 {
 	while (sem_wait(sem) == -1) { // interrupted by syscall? 
 		if (errno == EINTR) {
@@ -224,7 +297,12 @@ void wait_sem(sem_t *sem)
 	return;
 }
 
-void putSolution(int *solution)
+/**
+ * @details Function which writes a solution to the shared memory buffer.
+ * @param solution The solution to be written to shared memory.
+ * @return This function has no return value.
+ */
+static void putSolution(int *solution)
 {
 	wait_sem(sWriteEnd);
 
@@ -248,7 +326,14 @@ void putSolution(int *solution)
 	sem_post(sWriteEnd);
 }
 
-int findIndex(int array[], int value, int size)
+/**
+ * @details Function which finds the index of a specific value in an array.
+ * @param array The array in which the desired value resides.
+ * @param value The value to search for.
+ * @param size The size of the array.
+ * @return -1 if value not found in array. The index of value if found.
+ */
+static int findIndex(int array[], int value, int size)
 {
 	int index = 0;
 	while (index < size && array[index] != value)
@@ -257,7 +342,15 @@ int findIndex(int array[], int value, int size)
 	return (index == size ? -1 : index);
 }
 
-void genSolution(int permutation[], int V, int *solution)
+/**
+ * @details Function which receives a random permutation of the nodes and finds
+ *          a random set of edges which - if removed - leave an acyclic graph.
+ * @param permutation The random permutation of the nodes.
+ * @param V The number of nodes in the graph.
+ * @param solution Contains the solution of edges at the end.
+ * @return This function has no return value.
+ */
+static void genSolution(int permutation[], int V, int *solution)
 {
 	if (shared->quit == 1) {
 		quit = 1;
@@ -302,6 +395,15 @@ void genSolution(int permutation[], int V, int *solution)
 	}
 }
 
+/**
+ * The main entry point of the program.
+ * @details Sets up signal handler, shared memory and semaphores, parses the
+ *          commandline arguments and periodically generates a new solution and
+ *          submits it to the shared memory.
+ * @param argc The number of commandline arguments.
+ * @param argv The array of commandline arguments.
+ * @return 0 on success, non-zero on failure.
+ */
 int main(int argc, char *argv[])
 {
 	if (argc == 1)