Closes #22

examples/input_bytes/input.c

@@ -1,6 +1,9 @@
 #include <stdbool.h>
+// Keeps process running until Ctrl-C is pressed.
+// Contains a SIGINT handler and keep_process_running variable.
 #include "util/exit_handling.h"
 #include "util/output_handling.h"
+// Main RMR header file
 #include "midi/midi_handling.h"
 
 Alsa_MIDI_data * data;
@@ -14,44 +17,57 @@ MIDI_message * msg;
 error_message * err_msg;
 
 int main() {
+    // Allocate a MIDI_in_data instance, assign a
+    // MIDI message queue and an error queue
     prepare_input_data_with_queues(&input_data);
 
     // Create a port configuration with default values
     setup_port_config(&port_config, MP_IN);
     // Start a port with a provided configruation
     start_port(&data, port_config);
 
+    // Allocate memory for a MIDI_port instance
     init_midi_port(&current_midi_port);
 
-    // Assigns amidi_data to input_data instance
+    // Assign amidi_data to input_data instance
     assign_midi_data(input_data, data);
 
     // Count the MIDI ports,
     // open if a port containing "Synth" is available
     if (find_midi_port(data, current_midi_port, "rmr", false) > 0) {
         print_midi_port(current_midi_port);
         open_port(true, data, current_midi_port->id, current_midi_port->port_info_name, input_data);
+        // Don't exit until Ctrl-C is pressed;
+        // Look up "output_handling.h"
         keep_process_running = 1;
     }
 
-    // Add SIGINT handler
+    // Add a SIGINT handler to set keep_process_running to 0
+    // so the program can exit
     signal(SIGINT, sigint_handler);
 
     // Run until SIGINT is received
     while (keep_process_running) {
         while (g_async_queue_length_unlocked(input_data->midi_async_queue)) {
+            // Read a message from a message queue
             msg = g_async_queue_try_pop(input_data->midi_async_queue);
             if (msg != NULL) {
+                // Print and deallocate a midi message instance
                 print_midi_msg_buf(msg->buf, msg->count);
                 free_midi_message(msg);
             }
         }
         while (g_async_queue_length_unlocked(input_data->error_async_queue)) {
+            // Read an error message from an error queue,
+            // simply deallocate it for now
             err_msg = g_async_queue_try_pop(input_data->midi_async_queue);
             if (err_msg != NULL) free_error_message(err_msg);
         }
     }
 
+    // Close a MIDI input port,
+    // shutdown the input thread,
+    // do cleanup
     destroy_midi_input(data, input_data);
 
     // Destroy a port configuration

examples/output/output.c

@@ -1,8 +1,13 @@
 #include <stdio.h>
 #include <stdbool.h>
-#include <unistd.h> // usleep
-#include <time.h>   // nanosleep
+// Needed for usleep
+#include <unistd.h>
+// Needed for nanosleep
+#include <time.h>
+// Main RMR header file
 #include "midi/midi_handling.h"
+// Keeps process running until Ctrl-C is pressed.
+// Contains a SIGINT handler and keep_process_running variable.
 #include "util/exit_handling.h"
 #include "util/timing.h"
 #include "test_data.h"
@@ -26,29 +31,34 @@ int main() {
     // Start a port with a provided configruation
     start_port(&data, port_config);
 
-    // Allocate memory for a midi port struct to fill TODO elaborate
+    // Allocate memory for a MIDI_port instance
     init_midi_port(&current_midi_port);
 
     // Count the MIDI ports,
     // open if a port containing a certain word is available
     if (find_midi_port(data, current_midi_port, "rmr", true) > 0) {
         print_midi_port(current_midi_port);
         open_port(false, data, current_midi_port->id, current_midi_port->port_info_name, NULL);
+        // Don't exit until Ctrl-C is pressed;
+        // Look up "output_handling.h"
         keep_process_running = 1;
     }
 
     // Send out a series of MIDI messages.
     send_midi_message(data, MIDI_PROGRAM_CHANGE_MSG, 2);
     send_midi_message(data, MIDI_CONTROL_CHANGE_MSG, 3);
 
-    // Add SIGINT handler
+    // Add a SIGINT handler to set keep_process_running to 0
+    // so the program can exit
     signal(SIGINT, sigint_handler);
 
-    // Generate notes until SIGINT
+    // Run until SIGINT is received
     while (keep_process_running) {
         if (millis() - timer_msec_last > 100.) {
             timer_msec_last = millis();
+            // Send a Note On message
             if (msg_mode) send_midi_message(data, MIDI_NOTE_ON_MSG, 3);
+            // Send a Note Off message
             else          send_midi_message(data, MIDI_NOTE_OFF_MSG, 3);
             printf("mode: %d\n", msg_mode);
             msg_mode = !msg_mode;
@@ -57,6 +67,8 @@ int main() {
         }
     }
 
+    // Destroy a MIDI output port:
+    // close a port connection and perform a cleanup.
     if (destroy_midi_output(data, NULL) != 0) slog("destructor", "destructor error");
 
     // Destroy a port configuration

examples/virtual_input_bytes/virtual_input.c

@@ -1,8 +1,11 @@
 #include <stdio.h>
 #include <stdbool.h>
+// Keeps process running until Ctrl-C is pressed.
+// Contains a SIGINT handler and keep_process_running variable.
 #include "util/exit_handling.h"
 #include "util/output_handling.h"
 #include "util/midi_parsing.h"
+// Main RMR header file
 #include "midi/midi_handling.h"
 
 Alsa_MIDI_data * data;
@@ -14,38 +17,50 @@ error_message * err_msg;
 RMR_Port_config * port_config;
 
 int main() {
-    //
+    // Allocate a MIDI_in_data instance, assign a
+    // MIDI message queue and an error queue
     prepare_input_data_with_queues(&input_data);
+
     // Create a port configuration with default values
     setup_port_config(&port_config, MP_VIRTUAL_IN);
     // Start a port with a provided configruation
     start_port(&data, port_config);
-    //
+
+    // Assign amidi_data to input_data instance
     assign_midi_data(input_data, data);
+
     // Open a new port with a pre-set name
     open_virtual_port(data, "rmr", input_data);
 
+    // Don't exit until Ctrl-C is pressed;
+    // Look up "output_handling.h"
     keep_process_running = 1;
 
-    // Add SIGINT handler
+    // Add a SIGINT handler to set keep_process_running to 0
+    // so the program can exit
     signal(SIGINT, sigint_handler);
 
     // Run until SIGINT is received
     while (keep_process_running) {
         while (g_async_queue_length_unlocked(input_data->midi_async_queue)) {
+            // Read a message from a message queue
             msg = g_async_queue_try_pop(input_data->midi_async_queue);
             if (msg != NULL) {
                 print_midi_msg_buf(msg->buf, msg->count);
                 free_midi_message(msg);
             }
         }
         while (g_async_queue_length_unlocked(input_data->error_async_queue)) {
+            // Read an error message from an error queue,
+            // simply deallocate it for now
             err_msg = g_async_queue_try_pop(input_data->midi_async_queue);
             if (err_msg != NULL) free_error_message(err_msg);
         }
     }
 
-    // TODO
+    // Close a MIDI input port,
+    // shutdown the input thread,
+    // do cleanup
     destroy_midi_input(data, input_data);
 
     // Destroy a port configuration

examples/virtual_input_detailed/virtual_input.c

@@ -1,7 +1,10 @@
 #include <stdio.h>
 #include <stdbool.h>
+// Keeps process running until Ctrl-C is pressed.
+// Contains a SIGINT handler and keep_process_running variable.
 #include "util/exit_handling.h"
 #include "util/midi_parsing.h"
+// Main RMR header file
 #include "midi/midi_handling.h"
 
 Alsa_MIDI_data * data;
@@ -44,11 +47,11 @@ void print_midi_msg_buf(unsigned char * buf, long count) {
     fflush( stdout );
 }
 
-
-
 int main() {
-    //
+    // Allocate a MIDI_in_data instance, assign a
+    // MIDI message queue and an error queue
     prepare_input_data_with_queues(&input_data);
+
     // Create a port configuration with default values
     setup_port_config(&port_config, MP_VIRTUAL_IN);
     // Start a port with a provided configruation
@@ -58,27 +61,35 @@ int main() {
     // Open a new port with a pre-set name
     open_virtual_port(data, "rmr", input_data);
 
+    // Don't exit until Ctrl-C is pressed;
+    // Look up "output_handling.h"
     keep_process_running = 1;
 
-    // Add SIGINT handler
+    // Add a SIGINT handler to set keep_process_running to 0
+    // so the program can exit
     signal(SIGINT, sigint_handler);
 
     // Run until SIGINT is received
     while (keep_process_running) {
         while (g_async_queue_length_unlocked(input_data->midi_async_queue)) {
+            // Read a message from a message queue
             msg = g_async_queue_try_pop(input_data->midi_async_queue);
             if (msg != NULL) {
                 print_midi_msg_buf(msg->buf, msg->count);
                 free_midi_message(msg);
             }
         }
         while (g_async_queue_length_unlocked(input_data->error_async_queue)) {
+            // Read an error message from an error queue,
+            // simply deallocate it for now
             err_msg = g_async_queue_try_pop(input_data->midi_async_queue);
             if (err_msg != NULL) free_error_message(err_msg);
         }
     }
 
-    // TODO
+    // Close a MIDI input port,
+    // shutdown the input thread,
+    // do cleanup
     destroy_midi_input(data, input_data);
 
     // Destroy a port configuration

examples/virtual_output/virtual_output.c

@@ -1,8 +1,13 @@
 #include <stdio.h>
 #include <stdbool.h>
-#include <unistd.h> // usleep
-#include <time.h>   // nanosleep
+// Needed for usleep
+#include <unistd.h>
+// Needed for nanosleep
+#include <time.h>
+// Main RMR header file
 #include "midi/midi_handling.h"
+// Keeps process running until Ctrl-C is pressed.
+// Contains a SIGINT handler and keep_process_running variable.
 #include "util/exit_handling.h"
 #include "util/timing.h"
 #include "test_data.h"
@@ -29,15 +34,20 @@ int main() {
     send_midi_message(amidi_data, MIDI_PROGRAM_CHANGE_MSG, 2);
     send_midi_message(amidi_data, MIDI_CONTROL_CHANGE_MSG, 3);
 
-    // Add SIGINT handler
+    // Add a SIGINT handler to set keep_process_running to 0
+    // so the program can exit
     signal(SIGINT, sigint_handler);
+    // Don't exit until Ctrl-C is pressed;
+    // Look up "output_handling.h"
     keep_process_running = 1;
 
-    // Generate notes until SIGINT
+    // Run until SIGINT is received
     while (keep_process_running) {
         if (millis() - timer_msec_last > 100.) {
             timer_msec_last = millis();
+            // Send a Note On message
             if (msg_mode) send_midi_message(amidi_data, MIDI_NOTE_ON_MSG, 3);
+            // Send a Note Off message
             else          send_midi_message(amidi_data, MIDI_NOTE_OFF_MSG, 3);
             printf("mode: %d\n", msg_mode);
             msg_mode = !msg_mode;
@@ -46,6 +56,8 @@ int main() {
         }
     }
 
+    // Destroy a MIDI output port:
+    // close a port connection and perform a cleanup.
     if (destroy_midi_output(amidi_data, NULL) != 0) slog("destructor", "destructor error");
 
     // Destroy a port configuration

include/midi/midi_handling.h

@@ -1153,7 +1153,7 @@ void close_port(Alsa_MIDI_data * amidi_data, MIDI_in_data * input_data, int mode
 }
 
 /**
- * Destroys a MIDI output port.
+ * Destroys a MIDI output port: closes a port connection and performs a cleanup.
  *
  * :param amidi_data: :c:type:`Alsa_MIDI_data` instance
  * :param input_data: :c:type:`MIDI_in_data` instance
@@ -1178,7 +1178,8 @@ int destroy_midi_output(Alsa_MIDI_data * amidi_data, MIDI_in_data * input_data)
 }
 
 /**
- * Destroys a MIDI input port.
+ * Destroys a MIDI input port:
+ * closes a port connection, shuts the input thread down, performs cleanup / deallocations.
  *
  * :param amidi_data: :c:type:`Alsa_MIDI_data` instance
  * :param input_data: :c:type:`MIDI_in_data` instance