kern/shell: add comments

1 files changed, 27 insertions, 0 deletions

diff --git a/kern/shell.c b/kern/shell.c
index ba756a5f..38f29912 100644
--- a/kern/shell.c
+++ b/kern/shell.c
@@ -224,6 +224,10 @@ shell_cmd_lookup(const char *name)
 }
 
 /*
+ * Look up the first command that matches a given string.
+ *
+ * The input string is defined by the given string pointer and size.
+ *
  * The global lock must be acquired before calling this function.
  */
 static const struct shell_cmd *
@@ -242,6 +246,21 @@ shell_cmd_match(const struct shell_cmd *cmd, const char *str,
 }
 
 /*
+ * Attempt command auto-completion.
+ *
+ * The given string is the beginning of a command, or the empty string.
+ * The sizep parameter initially points to the size of the given string.
+ * If the string matches any registered command, the cmdp pointer is
+ * updated to point to the first matching command in the sorted list of
+ * commands, and sizep is updated to the number of characters in the
+ * command name that are common in subsequent commands. The command
+ * pointer and the returned size can be used to print a list of commands
+ * eligible for completion.
+ *
+ * If there is a single match for the given string, return 0. If there
+ * are more than one match, return ERROR_AGAIN. If there is no match,
+ * return ERROR_INVAL.
+ *
  * The global lock must be acquired before calling this function.
  */
 static int
@@ -309,6 +328,10 @@ shell_cmd_complete(const char *str, unsigned long *sizep,
 }
 
 /*
+ * Print a list of commands eligible for completion, starting at the
+ * given command. Other eligible commands share the same prefix, as
+ * defined by the size argument.
+ *
  * The global lock must be acquired before calling this function.
  */
 static void
@@ -811,6 +834,10 @@ shell_process_raw_char(char c)
         goto out;
     }
 
+    /*
+     * This assumes that the backspace character only moves the cursor
+     * without erasing characters.
+     */
     printf("%s", shell_line_str(current_line) + shell_cursor - 1);
     remaining_chars = shell_line_size(current_line) - shell_cursor;