Add function docs and fix syntax

Makefile

@@ -13,10 +13,16 @@ SOURCES  := $(SRCDIR)/$(TARGET).c
 INCLUDES := $(wildcard $(SRCDIR)/*.h)
 OBJECTS  := $(SOURCES:$(SRCDIR)/%.c=$(OBJDIR)/%.o)
 
+$(BINDIR)/$(TARGET): $(BINDIR)
+$(BINDIR):
+	mkdir -p $(BINDIR)
 $(BINDIR)/$(TARGET): $(OBJECTS)
 	@$(LINKER) $(OBJECTS) $(LFLAGS) -o $@
 	@echo "Linking complete."
 
+$(OBJECTS): | $(OBJDIR)
+$(OBJDIR):
+	mkdir -p $(OBJDIR)
 $(OBJECTS): $(OBJDIR)/%.o : $(SRCDIR)/%.c
 	@$(CC) $(CFLAGS) -c $< -o $@
 	@echo "Compiled "$<" successfully."

src/api/default.c

 /**
- * Default callback function called if no other endpoint matches.
+ * Default callback function, returning a 404 response.
+ * @param[in]   request   incoming HTTP request
+ * @param[out]  response  HTTP response to the request
+ * @param[in]   user_data extra data to pass between main thread and callbacks
+ * @return                internal status code
  */
-int callback_default
-(
-    const struct _u_request * request,
-    struct _u_response * response,
-    void * user_data
-)
+int callback_default(const struct _u_request * request,
+    struct _u_response * response, void * user_data)
 {
     ulfius_set_string_body_response(response, 404, "Unknown endpoint");
     return U_CALLBACK_CONTINUE;

src/api/encryption_unlock.c

 /**
  * Callback function that uses the password passed in the request to open the
  * luks volume.
+ * @param[in]   request   incoming HTTP request
+ * @param[out]  response  HTTP response to the request
+ * @param[in]   user_data extra data to pass between main thread and callbacks
+ * @return                internal status code
  */
-int callback_encryption_unlock
-(
-    const struct _u_request * request,
-    struct _u_response * response,
-    void * user_data
-)
+int callback_encryption_unlock(const struct _u_request * request,
+    struct _u_response * response, void * user_data)
 {
     json_t * json_input = ulfius_get_json_body_request(request, NULL);
     const char * password;
@@ -18,12 +18,8 @@ int callback_encryption_unlock
         return send_simple_response(response, 400, "error", "missing password");
     }
   
-    int unlock_status = encryption_unlock
-    (
-        CONTAINER_DEVICE,
-        MAPPED_DEVICE_NAME,
-        password
-    );
+    int unlock_status = encryption_unlock(CONTAINER_DEVICE, MAPPED_DEVICE_NAME,
+        password);
   
     if (unlock_status == -1)
     {

src/auxiliary.c

@@ -13,26 +13,28 @@ void stop_server()
 
 /**
  * Read a file completely into a string.
+ * @param  filename Path to the file to read.
+ * @return          Contents of the file.
  */
 char * read_file(const char * filename)
 {
     char * buffer = NULL;
     long length;
-    FILE * f = fopen(filename, "rb");
+    FILE * file = fopen(filename, "rb");
     if (filename != NULL)
     {
-        if (f)
+        if (file)
         {
-            fseek(f, 0, SEEK_END);
-            length = ftell (f);
-            fseek(f, 0, SEEK_SET);
+            fseek(file, 0, SEEK_END);
+            length = ftell(file);
+            fseek(file, 0, SEEK_SET);
             buffer = o_malloc(length + 1);
             if (buffer)
             {
-                fread(buffer, 1, length, f);
+                fread(buffer, 1, length, file);
             }
             buffer[length] = '\0';
-            fclose (f);
+            fclose (file);
         }
         return buffer;
     }
@@ -44,14 +46,13 @@ char * read_file(const char * filename)
 
 /**
  * Respond to the request with a simple json structure '{$field: $value}'.
+ * @param  response    response struct to use
+ * @param  http_status HTTP status code to return
+ * @param  field       name of the json field to return
+ * @param  value       json value to return
  */
-int send_simple_response
-(
-    struct _u_response * response, /* response struct to use */
-    int http_status,               /* HTTP status code to return */
-    const char *field,             /* name of the json field to return */
-    const char *value              /* json value to return */
-)
+int send_simple_response(struct _u_response * response, int http_status,
+    const char * field, const char * value)
 {
     json_t * json_body = NULL;
     json_body = json_object();

src/cryptops-api.c

-#include <includes.h>
-#include <settings.h>
+#include <includes/common-includes.h>
+#include <includes/settings.h>
 
 #define FIFO_PATH "/tmp/cryptops-api-stop"
 
@@ -8,7 +8,7 @@
 #include <api/default.c>
 #include <api/encryption_unlock.c>
 
-int main(int argc, char **argv)
+int main(int argc, char ** argv)
 {
     y_init_logs("cryptops-api", Y_LOG_MODE_CONSOLE, Y_LOG_LEVEL_DEBUG,
         NULL, "Starting cryptops-api");
@@ -38,7 +38,8 @@ int main(int argc, char **argv)
     {
         // If command-line options are -secure <key_file> <cert_file>,
         // then listen for https connections.
-        char * key_pem = read_file(argv[2]), * cert_pem = read_file(argv[3]);
+        char * key_pem = read_file(argv[2]);
+        char * cert_pem = read_file(argv[3]);
         ret = ulfius_start_secure_framework(&instance, key_pem, cert_pem);
         o_free(key_pem);
         o_free(cert_pem);

src/encryption_functions.c

@@ -2,12 +2,11 @@
  * Use cryptsetup to initialise the luks container.
  * It will not be opened (decrypted) yet, but it does check if the container
  * seems usable.
+ * @param crypt_device struct to store crypt device context
+ * @param crypt_device path to the encrypted container
+ * @return             status code
  */
-static int container_initialise
-(
-    struct crypt_device **cd, /* struct to store crypt device context */
-    const char *path          /* path to the encrypted container */
-)
+static int container_initialise(struct crypt_device **cd, const char *path)
 {
     // Let LUKS initialise the encrypted device.
     int r = crypt_init(cd, path);
@@ -19,12 +18,7 @@ static int container_initialise
     }
 
     // Load the LUKS header from the block device into the crypt device context.
-    r = crypt_load
-    (
-        *cd,         /* crypt device context */
-        CRYPT_LUKS1, /* requested encryption type */
-        NULL         /* additional parameters (not used) */
-    );
+    r = crypt_load(*cd, CRYPT_LUKS1, NULL);
     if (r < 0)
     {
         printf("crypt_load() failed on device %s.\n",
@@ -37,13 +31,13 @@ static int container_initialise
 /**
  * Use cryptsetup to unlock the luks container.
  * This will create `/dev/mapper/$device_name`.
+ * @param path        path to the encrypted container
+ * @param device_name name of the mapping
+ * @param password    encryption password of the container
+ * @return            status code
  */
-static int encryption_unlock
-(
-    const char *path,        /* path to the encrypted container */
-    const char *device_name, /* name of the mapping */
-    const char *password     /* encryption password of the container */
-)
+static int encryption_unlock(const char *path, const char *device_name,
+    const char *password)
 {
     // Let LUKS initialise the encrypted device.
     struct crypt_device *cd;
@@ -56,16 +50,9 @@ static int encryption_unlock
         return r;
     }
 
-    // Device activation creates device-mapper devie mapping with namei
-    // device_name.
-    r = crypt_activate_by_passphrase
-    (
-        cd,                          /* crypt context */
-        device_name,                 /* device name to activate */
-        CRYPT_ANY_SLOT,              /* which slot use (ANY - try all) */
-        password, strlen(password),  /* passphrase */
-        CRYPT_ACTIVATE_READONLY      /* flags */
-    );
+    // Create device mapping with name device_name.
+    r = crypt_activate_by_passphrase(cd, device_name, CRYPT_ANY_SLOT,
+        password, strlen(password), 0);
     if (r < 0)
     {
         printf("Device %s activation failed.\n", device_name);