Improve documentation in shell.c

The shell main loop function and text input function were dreadfully
devoid of comments.  This simply could not continue, so I added a
sprinkling of comments to each, as well as to important sections of the
file.  Further, I changed the special character values to look like
characters rather than numbers, which should aid in understanding.

src/shell.c

     .status = PDB_CONFIG_STATUS_VALID
 };
 
+/*
+ * Command functions
+ */
+
 static void cmd_license(BaseSequentialStream *chp, int argc, char *argv[])
 {
     (void) argv;
     chEvtSignal(pdb_led_thread, PDB_EVT_LED_IDENTIFY);
 }
 
+/*
+ * List of shell commands
+ */
 static const struct pdb_shell_cmd commands[] = {
     {"license", cmd_license, "Show copyright and license information"},
     {"erase", cmd_erase, "Erase all stored configuration"},
     {NULL, NULL, NULL}
 };
 
+/*
+ * The shell's configuration
+ */
 const struct pdb_shell_cfg shell_cfg = {
     (BaseSequentialStream *)&SDU1,
     commands
 }
 
 /*
- * PD Buddy configuration shell
- *
- * p: The configuration for the shell itself
+ * PD Buddy Sink configuration shell
  */
 void pdb_shell(void)
 {
     char *args[PDB_SHELL_MAX_ARGUMENTS + 1];
 
     while (true) {
+        /* Print the prompt */
         chprintf(chp, "PDBS) ");
+
+        /* Read a line of input */
         if (shellGetLine(chp, line, sizeof(line))) {
+            /* If a command was not entered, prompt again */
             chprintf(chp, "\r\n");
             continue;
         }
+
+        /* Tokenize the line */
         lp = _strtok(line, " \t", &tokp);
         cmd = lp;
         n = 0;
         while ((lp = _strtok(NULL, " \t", &tokp)) != NULL) {
+            /* If we have too many tokens, abort */
             if (n >= PDB_SHELL_MAX_ARGUMENTS) {
                 chprintf(chp, "too many arguments\r\n");
                 cmd = NULL;
             args[n++] = lp;
         }
         args[n] = NULL;
+
+        /* If there's a command to run, run it */
         if (cmd != NULL) {
+            /* Handle "help" in a special way */
             if (strcmp(cmd, "help") == 0) {
                 if (n > 0) {
                     chprintf(chp, "Usage: help\r\n");
                 if (scp != NULL)
                     list_commands(chp, scp);
             }
+            /* Run a command, giving a generic error message if there is no
+             * such command */
             else if ((scp == NULL) || cmdexec(scp, chp, cmd, n, args)) {
                 chprintf(chp, "%s", cmd);
                 chprintf(chp, " ?\r\n");
     while (true) {
         char c;
 
+        /* Read a character */
         if (chSequentialStreamRead(chp, (uint8_t *)&c, 1) == 0)
             return true;
-        if (c == 4) {
+        /* Abort if ^D is received */
+        if (c == '\x04') {
             chprintf(chp, "^D");
             return true;
         }
-        if ((c == 8) || (c == 127)) {
+        /* Delete a character if ASCII backspace or delete is received */
+        if ((c == '\b') || (c == '\x7F')) {
             if (p != line) {
                 chSequentialStreamPut(chp, 0x08);
                 chSequentialStreamPut(chp, 0x20);
             }
             continue;
         }
+        /* Finish reading input if Enter is pressed */
         if (c == '\r') {
             chprintf(chp, "\r\n");
             *p = 0;
             return false;
         }
-        if (c < 0x20)
+        /* Ignore other non-printing characters */
+        if (c < ' ')
             continue;
+        /* If there's room in the line buffer, append the new character */
         if (p < line + size - 1) {
             chSequentialStreamPut(chp, c);
             *p++ = (char)c;