Index: src/debug.c
===================================================================
--- src/debug.c	(revision 18582)
+++ src/debug.c	(working copy)
@@ -46,20 +46,25 @@
 
 =item C<static char* nextarg(char* command)>
 
-Returns the position just past the current argument in a PASM
-instruction. This is not the same as C<na()>, above, which is intended
-for debugger commands. This function is used for C<eval>.
+Returns the position just past the current argument in the PASM
+instruction C<command>. This is not the same as C<na()>, above,
+which is intended for debugger commands. This function is used for C<eval>.
 
 =cut
 
 */
 
-static char*
-nextarg(char* command)
+static char const *
+nextarg(char const *command)
 {
+    /* as long as the character pointed to by command is not NULL,
+     * and it is either alphanumeric, a comma or a closing bracket,
+     * continue looking for the next argument.
+     */
     while (*command && (isalnum((int) *command) || *command == ',' ||
         *command == ']'))
             command++;
+    /* Try to eat as much space as we can */
     while (*command && isspace((int) *command))
         command++;
     return command;
@@ -75,11 +80,13 @@
 
 */
 
-static const char*
-skip_ws(const char* str)
+static const char *
+skip_ws(const char *str)
 {
+    /* as long as str is not NULL and it contains space, skip it */
     while (*str && isspace((int) *str))
         str++;
+
     return str;
 }
 
@@ -94,31 +101,37 @@
 
 */
 
-static const char*
-skip_command(const char* str)
+static const char *
+skip_command(const char * str)
 {
+    /* while str is not null and it contains a command (no spaces),
+     * skip the character
+     */
     while (*str && !isspace((int) *str))
         str++;
+    /* and eat all space after that */
     while (*str && isspace((int) *str))
         str++;
+
     return str;
 }
 
 /*
 
-=item C<static const char* parse_int(const char* str, int* intP)>
+=item C<static const char *parse_int(const char *str, int *intP)>
 
 Parse an C<int> out of a string and return a pointer to just after the
-C<int>.
+C<int>. The parameter C<intP> is an output parameter, and contains the
+value that is parsed.
 
 =cut
 
 */
 
-static const char*
-parse_int(const char* str, int* intP)
+static const char *
+parse_int(const char *str, int *intP)
 {
-    char* end;
+    char *end;
 
     *intP = strtol(str, &end, 0);
 
@@ -127,46 +140,54 @@
 
 /*
 
-=item C<static const char*
-parse_string(Interp *interp,
-             const char* str, STRING** strP)>
+=item C<static const char *parse_string(Interp *interp,
+                                        const char* str, STRING** strP)>
 
 Parse a double-quoted string out of a C string and return a pointer to
 just after the string. The parsed string is converted to a Parrot
-C<STRING>.
+C<STRING>, which is returned through the output parameter C<strP>.
 
 =cut
 
 */
 
 static const char*
-parse_string(Interp *interp,
-             const char* str, STRING** strP)
+parse_string(Interp *interp, const char *str, STRING **strP)
 {
-    const char* string;
+    const char* string_start;
 
+    /* if this is not a quoted string, then nothing to parse, return NULL */
     if (*str != '"')
         return NULL;
-    str++;
-    string = str;
+        
+    str++; /* skip the '"' */
+    string_start = str; /* remember where the string starts */
+    
+    /* continue parsing while we don't see the closing quote */
     while (*str && *str != '"') {
+        /* check for escaped quotes, if any, skip \ and ". */
         if (*str == '\\' && str[1])
             str += 2;
-        else
+        else /* no escape character */
             str++;
     }
 
-    *strP = string_make(interp, string, str - string, NULL, 0);
+    /* create a string with length str - string_start, and assign it
+     * to the output parameter strP
+     */
+    *strP = string_make(interp, string_start, str - string_start, NULL, 0);
 
+    /* XXX I don't know why this is */
     if (*str)
         str++;
+        
     return str;
 }
 
 /*
 
-=item C<static const char*
-parse_key(Interp *interp, const char* str, PMC** keyP)>
+=item C<static const char *parse_key(Interp *interp, const char* str, 
+                                     PMC** keyP)>
 
 Parse an aggregate key out of a string and return a pointer to just
 after the key. Currently only string and integer keys are allowed.
@@ -176,35 +197,47 @@
 */
 
 static const char*
-parse_key(Interp *interp, const char* str, PMC** keyP)
+parse_key(Interp *interp, const char *str, PMC **keyP)
 {
-    *keyP = NULL;
-    if (*str != '[')
+    *keyP = NULL; /* clear output parameter */
+    
+    if (*str != '[') /* if '[', then no key, return NULL */
         return NULL;
+        
     str++; /* Skip [ */
-    if (*str == '"') {
-        STRING* string;
-        str = parse_string(interp, str, &string);
-        *keyP = key_new_string(interp, string);
+    
+    /* if this is a string key, parse the string, and create a
+     * new key string, returned through keyP output parameter.
+     */
+    if (*str == '"') { 
+        STRING* parrot_string;
+        str = parse_string(interp, str, &parrot_string);
+        *keyP = key_new_string(interp, parrot_string);
     }
-    else if (isdigit((int) *str)) {
+    else if (isdigit((int) *str)) { /* it is a numeric key */
         int value;
         str = parse_int(str, &value);
+        /* return a new integer key through keyP output parameter */
         *keyP = key_new_integer(interp, (INTVAL) value);
     }
-    else {
+    else { /* neither a string nor a numeric key, 'not supported case'. */
         return NULL;
     }
 
+    /* XXX I think, we should match a ']' now, if not, it is an error,
+     * in which case we should return NULL 
+     */
     if (*str != ']')
         return NULL;
+    
+    /* skip the ']', before returning the pointer to the command */    
     return ++str;
 }
 
 /*
 
-=item C<static const char*
-parse_command(const char* command, unsigned long* cmdP)>
+=item C<static const char *parse_command(const char *command, 
+                                         unsigned long *cmdP)>
 
 Convert the command at the beginning of a string into a numeric value
 that can be used as a switch key for fast lookup.
@@ -213,12 +246,13 @@
 
 */
 
-static const char*
-parse_command(const char* command, unsigned long* cmdP)
+static const char *
+parse_command(const char *command, unsigned long *cmdP)
 {
     int i;
     unsigned long c = 0;
 
+    
     if (*command == '\0') {
         *cmdP = c;
         return 0;