main: Add some documentation

Some tricks like defaulting the source and sink file descriptors to
stdin and stdout aren't necessarily obvious, so add some commentary and
justifications throughout.

Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I515f36857a7056aa589ecbb09c46372ec4d3976d
diff --git a/main.c b/main.c
index 1f00ada..871da1d 100644
--- a/main.c
+++ b/main.c
@@ -1,6 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2021 IBM Corp.
 
+/*
+ * debug-trigger listens for an external signal that the BMC is in some way unresponsive. When the
+ * signal is received it triggers a crash to collect debug data and reboots the system in the hope
+ * that it will recover.
+ *
+ * Usage: debug-trigger [SOURCE] [SINK]
+ *
+ * Examples:
+ *  debug-trigger
+ *	Set the source as stdin and the sink as stdout. Useful for testing.
+ *
+ *  debug-trigger /dev/serio_raw0 /proc/sysrq-trigger
+ *	Open /dev/serio_raw0 as the source and /proc/sysrq-trigger as the sink.
+ */
+
 #include <err.h>
 #include <fcntl.h>
 #include <getopt.h>
@@ -81,6 +96,7 @@
 	int source;
 	int sink;
 
+	/* Option processing. Currently nothing implemented, but allows us to use optind */
 	while (1) {
 		static struct option long_options[] = {
 			{0, 0, 0, 0},
@@ -92,12 +108,22 @@
 			break;
 	}
 
+	/*
+	 * The default behaviour sets the source as stdin and the sink as stdout. This allows
+	 * trivial testing on the command-line with just a keyboard and without crashing the system.
+	 */
 	source = 0;
 	sink = 1;
 
+	/* Handle the source argument, if any */
 	if (optind < argc) {
 		char devpath[PATH_MAX];
 
+		/*
+		 * To make our lives easy with udev we take the basename of the source argument and
+		 * look for it in /dev. This allows us to use %p (the devpath specifier) in the udev
+		 * rule to pass the device of interest to the systemd unit.
+		 */
 		strncpy(devpath, argv[optind], sizeof(devpath));
 		devpath[PATH_MAX - 1] = '\0';
 		devid = basename(devpath);
@@ -112,16 +138,23 @@
 		optind++;
 	}
 
+	/* Handle the sink argument, if any */
 	if (optind < argc) {
+		/*
+		 * Just open the sink path directly. If we ever need different behaviour then we
+		 * patch this bit when we know what we need.
+		 */
 		if ((sink = open(argv[optind], O_WRONLY)) == -1)
 			err(EXIT_FAILURE, "Failed to open %s", argv[optind]);
 
 		optind++;
 	}
 
+	/* Check we're done with the command-line */
 	if (optind < argc)
 		err(EXIT_FAILURE, "Found %d unexpected arguments", argc - optind);
 
+	/* Trigger the actions on the sink when we receive an event from the source */
 	if (process(source, sink) < 0)
 		errx(EXIT_FAILURE, "Failure while processing command stream");