Added comments for functions.

server.c

@@ -8,27 +8,61 @@
 
 #include "common.h"
 
+/**
+ * @details Constant which holds the port number to listen on.
+ */
 static const char *port = DEFAULT_PORT;
 
+/**
+ * @details Struct which holds info for the socket.
+ */
 static struct addrinfo *ai = NULL;
+
+/**
+ * @details Global variable for the socket file descriptor (easy cleanup).
+ */
 static int sockfd = -1;
+
+/**
+ * @details Global variable for the connection file descriptor (easy cleanup).
+ */
 static int connfd = -1;
+
+/**
+ * @details Global variable for the program name for error messages.
+ */
 static char* pname;
 
+/**
+ * @details Struct for storing ships.
+ */
 struct Ship {
         int shipsize;
         int hitcount;
         int isDestroyed;
 };
 
+/**
+ * @details Struct which points either to nil or a ship.
+ */
 struct Tile {
         int isHit;
         struct Ship *here;
 };
 
+/**
+ * @details Global array stores tiles which point to ships.
+ */
 static struct Tile field[MAP_SIZE][MAP_SIZE];
+
+/**
+ * @details Separate list of ships for easy traversing and cleanup.
+ */
 static struct Ship *ships[6];
 
+/**
+ * @details Variable which gets set on signal received.
+ */
 volatile sig_atomic_t quit = 0;
 
 /**
@@ -41,13 +75,23 @@ static void handle_signal(int signal)
         quit = 1;
 }
 
+/**
+ * @details Prints the program usage.
+ * @param void Function takes no arguments.
+ * @return Always non-zero.
+ */
 static void usage(void)
 {
         fprintf(stderr, "[%s] Usage:\n\tSYNOPSIS\n\t\tserver [-p PORT] SHIP1...\n\tEXAMPLE\n\tserver -p 1280 C2E2 F0H0 B6A6 E8E6 I2I5 H8I8\n", pname);
         exit(EXIT_FAILURE);
 }
 
-static void cleanup(void)
+/**
+ * @details Function for convenient cleanup of resources.
+ * @param void Function takes no arguments.
+ * @return 
+ */
+static int cleanup(void)
 {
         for (int i = 0; i < (int) sizeof(ships); i++) {
                 free(ships[i]);
@@ -59,8 +103,15 @@ static void cleanup(void)
 	}
 
         free(ai);
+
+	return 0;
 }
 
+/**
+ * @details Tests and adds a ship from the given coordinates to the ship array.
+ * @param coords The coordinates for the new ship.
+ * @return Returns the ship that has been added on success or exits the program.
+ */
 static struct Ship * addShip(char *coords)
 {
         if (strlen(coords) != 4) {
@@ -106,6 +157,12 @@ static struct Ship * addShip(char *coords)
         return newShip;
 }
 
+/**
+ * @details Parses the commandline arguments.
+ * @param argc The count of commandline arguments supplied.
+ * @param argv The array holding the commandline arguments.
+ * @return Calls the usage() function on error.
+ */
 static void parse(int argc, char *argv[])
 {
         if (argc == 1)
@@ -168,6 +225,11 @@ static void parse(int argc, char *argv[])
 	}
 }
 
+/**
+ * @details Check whether the player has won the game.
+ * @param void Function takes no parameters.
+ * @return 0 on not won and 1 when game won.
+ */
 static int checkWin(void)
 {
         int counter = 0;
@@ -183,6 +245,12 @@ static int checkWin(void)
         return 0;
 }
 
+/**
+ * @details Registers a hit on the internal game board.
+ * @param msg The encoded x and y coordinates of the hit.
+ * @return 0 on missed shot. 1 on ship hit but not destroyed. 2 on ship destroyed
+ *         but game still running. 3 on ship destroyed and all sunk.
+ */
 static int makeHit(uint16_t msg)
 {
         uint8_t y = msg & 0x003F;
@@ -215,6 +283,11 @@ static int makeHit(uint16_t msg)
         return 1; // ship hit but not destroyed
 }
 
+/**
+ * @details Calculates even parity for the received encoded coordinates.
+ * @param msg The received coordinates encoded in 2 bytes.
+ * @return 0 if parity OK, otherwise 1.
+ */
 static int checkParity(uint16_t msg)
 {
         uint16_t v = msg;
@@ -235,6 +308,11 @@ static int checkParity(uint16_t msg)
         }
 }
 
+/**
+ * @details Checks if the coordinates are valid.
+ * @param msg The received coordinates encoded in 2 bytes.
+ * @return 0 on success. 1 on failure.
+ */
 static int checkCoords(uint16_t msg)
 {
         uint8_t y = msg & 0x003F;
@@ -247,6 +325,15 @@ static int checkCoords(uint16_t msg)
         return 0;
 }
 
+/**
+ * The main entry point of the program.
+ * @details Signal handler is set up. The commandline arguments are parsed.
+ *          A socket gets created and listens for connections. Starts the game
+ *	    and finishes it appropriately.
+ * @param argc The count of commandline arguments.
+ * @param argv The array of commandline arguments.
+ * @return 0 on success. 1 on failure.
+ */
 int main(int argc, char *argv[])
 {
         struct sigaction sa;