2004-02-09 Elena Zannoni <ezannoni@redhat.com>

	* linespec.c (decode_line_1, locate_first_half)
	(decode_compound, lookup_prefix_sym): Update comments. Delete old
	commented out code.

2 files changed, 116 insertions, 47 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 5ef59fc682b..4b193fd6140 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,9 @@
+2004-02-09  Elena Zannoni  <ezannoni@redhat.com>
+
+	* linespec.c (decode_line_1, locate_first_half)
+	(decode_compound, lookup_prefix_sym): Update comments. Delete old
+	commented out code.
+
 2004-02-09  Daniel Jacobowitz  <drow@mvista.com>
 
 	* cp-namespace.c (check_one_possible_namespace_symbol): Don't use
diff --git a/gdb/linespec.c b/gdb/linespec.c
index e16e96ea16e..d362f1cc5f0 100644
--- a/gdb/linespec.c
+++ b/gdb/linespec.c
@@ -694,7 +694,11 @@ decode_line_1 (char **argptr, int funfirstline, struct symtab *default_symtab,
   /* Check to see if it's a multipart linespec (with colons or
      periods).  */
 
-  /* Locate the end of the first half of the linespec.  */
+  /* Locate the end of the first half of the linespec.
+     After the call, for instance, if the argptr string is "foo.c:123"
+     p will point at "123".  If there is only one part, like "foo", p
+     will point to "". If this is a C++ name, like "A::B::foo", p will
+     point to "::B::foo". Argptr is not changed by this call.  */
 
   p = locate_first_half (argptr, &is_quote_enclosed);
 
@@ -723,8 +727,13 @@ decode_line_1 (char **argptr, int funfirstline, struct symtab *default_symtab,
       if (is_quoted)
 	*argptr = *argptr + 1;
       
-      /* Is it a C++ or Java compound data structure?  */
-
+      /* Is it a C++ or Java compound data structure?
+	 The check on p[1] == ':' is capturing the case of "::",
+	 since p[0]==':' was checked above.  
+	 Note that the call to decode_compound does everything
+	 for us, including the lookup on the symbol table, so we
+	 can return now. */
+	
       if (p[0] == '.' || p[1] == ':')
 	return decode_compound (argptr, funfirstline, canonical,
 				saved_arg, p);
@@ -954,7 +963,9 @@ decode_indirect (char **argptr)
 /* Locate the first half of the linespec, ending in a colon, period,
    or whitespace.  (More or less.)  Also, check to see if *ARGPTR is
    enclosed in double quotes; if so, set is_quote_enclosed, advance
-   ARGPTR past that and zero out the trailing double quote.  */
+   ARGPTR past that and zero out the trailing double quote.
+   If ARGPTR is just a simple name like "main", p will point to ""
+   at the end.  */
 
 static char *
 locate_first_half (char **argptr, int *is_quote_enclosed)
@@ -1141,7 +1152,9 @@ decode_objc (char **argptr, int funfirstline, struct symtab *file_symtab,
 }
 
 /* This handles C++ and Java compound data structures.  P should point
-   at the first component separator, i.e. double-colon or period.  */
+   at the first component separator, i.e. double-colon or period.  As
+   an example, on entrance to this function we could have ARGPTR
+   pointing to "AAA::inA::fun" and P pointing to "::inA::fun".  */
 
 static struct symtabs_and_lines
 decode_compound (char **argptr, int funfirstline, char ***canonical,
@@ -1149,9 +1162,6 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
 {
   struct symtabs_and_lines values;
   char *p2;
-#if 0
-  char *q, *q1;
-#endif
   char *saved_arg2 = *argptr;
   char *temp_end;
   struct symbol *sym;
@@ -1162,9 +1172,10 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
   struct symbol **sym_arr;
   struct type *t;
 
-  /* First check for "global" namespace specification,
-     of the form "::foo".  If found, skip over the colons
-     and jump to normal symbol processing.  */
+  /* First check for "global" namespace specification, of the form
+     "::foo".  If found, skip over the colons and jump to normal
+     symbol processing.  I.e. the whole line specification starts with
+     "::" (note the condition that *argptr == p). */
   if (p[0] == ':' 
       && ((*argptr == p) || (p[-1] == ' ') || (p[-1] == '\t')))
     saved_arg2 += 2;
@@ -1190,10 +1201,35 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
      "B::C" separately as a symbol in the previous example.  */
 
   p2 = p;		/* Save for restart.  */
+
+  /* This is very messy. Following the example above we have now the
+     following pointers:
+     p -> "::inA::fun"
+     argptr -> "AAA::inA::fun
+     saved_arg -> "AAA::inA::fun
+     saved_arg2 -> "AAA::inA::fun
+     p2 -> "::inA::fun". */
+
+  /* In the loop below, with these strings, we'll make 2 passes, each
+     is marked in comments.*/
+
   while (1)
     {
+
+      /* Start of lookup in the symbol tables. */
+
+      /* Lookup in the symbol table the substring between argptr and
+	 p. Note, this call changes the value of argptr.  */
+      /* PASS1: Before the call, argptr->"AAA::inA::fun",
+	 p->"::inA::fun".  After the call: argptr->"inA::fun", p
+	 unchanged.  */
+      /* PASS2: Before the call, argptr->"AAA::inA::fun", p->"::fun".
+	 After the call: argptr->"fun", p->"::fun".  */
       sym_class = lookup_prefix_sym (argptr, p);
 
+      /* PASS1: assume sym_class == NULL. Skip the whole if-stmt. */
+      /* PASS2: assume sym_class has been found, i.e. "AAA::inA" is a
+	 class. Enter the if-stmt.  */
       if (sym_class &&
 	  (t = check_typedef (SYMBOL_TYPE (sym_class)),
 	   (TYPE_CODE (t) == TYPE_CODE_STRUCT
@@ -1211,51 +1247,54 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
 	    }
 	  else
 	    {
+	      /* PASS2: at this point argptr->"fun".  */
 	      p = *argptr;
 	      while (*p && *p != ' ' && *p != '\t' && *p != ',' && *p != ':')
 		p++;
+	      /* PASS2: at this point p->"".  String ended.  */
 	    }
-/*
-   q = operator_chars (*argptr, &q1);
-   if (q1 - q)
-   {
-   char *opname;
-   char *tmp = alloca (q1 - q + 1);
-   memcpy (tmp, q, q1 - q);
-   tmp[q1 - q] = '\0';
-   opname = cplus_mangle_opname (tmp, DMGL_ANSI);
-   if (opname == NULL)
-   {
-   cplusplus_error (saved_arg, "no mangling for \"%s\"\n", tmp);
-   }
-   copy = (char*) alloca (3 + strlen(opname));
-   sprintf (copy, "__%s", opname);
-   p = q1;
-   }
-   else
- */
-	  {
-	    copy = (char *) alloca (p - *argptr + 1);
-	    memcpy (copy, *argptr, p - *argptr);
-	    copy[p - *argptr] = '\0';
-	    if (p != *argptr
-		&& copy[p - *argptr - 1]
-		&& strchr (get_gdb_completer_quote_characters (),
-			   copy[p - *argptr - 1]) != NULL)
-	      copy[p - *argptr - 1] = '\0';
-	  }
+
+	  /* Allocate our own copy of the substring between argptr and
+	     p. */
+	  copy = (char *) alloca (p - *argptr + 1);
+	  memcpy (copy, *argptr, p - *argptr);
+	  copy[p - *argptr] = '\0';
+	  if (p != *argptr
+	      && copy[p - *argptr - 1]
+	      && strchr (get_gdb_completer_quote_characters (),
+			 copy[p - *argptr - 1]) != NULL)
+	    copy[p - *argptr - 1] = '\0';
+
+	  /* PASS2: At this point copy->"fun", p->"" */
 
 	  /* No line number may be specified.  */
 	  while (*p == ' ' || *p == '\t')
 	    p++;
 	  *argptr = p;
 
+	  /* Look for copy as a method of sym_class. */
+	  /* PASS2: at this point copy->"fun", sym_class is "AAA:inA".
+	     This concludes the scanning of the string for possible
+	     components matches.  If we find it here, we return. If
+	     not, and we are at the and of the string, we'll get out
+	     of the loop and lookup the whole string in the symbol
+	     tables.  */
+
 	  return find_method (funfirstline, canonical, saved_arg,
 			      copy, t, sym_class);
-	}
+	} /* End if symbol found */
 
+      /* End of lookup in the symbol tables.  */
+
+      /* Prepare for next run through the loop.  */
       /* Move pointer up to next possible class/namespace token.  */
+
       p = p2 + 1;	/* Restart with old value +1.  */
+
+      /* PASS1: at this point p2->"::inA::fun", so p->":inA::fun",
+	 i.e. if there is a double-colon, p will now point to the
+	 second colon. */
+
       /* Move pointer ahead to next double-colon.  */
       while (*p && (p[0] != ' ') && (p[0] != '\t') && (p[0] != '\''))
 	{
@@ -1266,6 +1305,14 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
 		error ("malformed template specification in command");
 	      p = temp_end;
 	    }
+	  /* Note that, since, at the start of this loop, p would be
+	     pointing to the second colon in a double-colon, we only
+	     satisfy the condition below if there is another
+	     double-colon to the right (after). I.e. there is another
+	     component that can be a class or a namespace. I.e, if at
+	     the beginning of this loop (PASS1), we had
+	     p->":inA::fun", we'll trigger this when p has been
+	     advanced to point to "::fun".  */
 	  else if ((p[0] == ':') && (p[1] == ':'))
 	    break;	/* Found double-colon.  */
 	  else
@@ -1273,10 +1320,20 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
 	}
 
       if (*p != ':')
-	break;		/* Out of the while (1).  */
-
-      p2 = p;		/* Save restart for next time around.  */
-      *argptr = saved_arg2;	/* Restore argptr.  */
+	break;		/* Out of the while (1).  This would happen
+			   for instance if we have looked up
+			   unsuccessfully all the components of the
+			   string, and p->"".  */
+
+      /* We get here if p points to ' ', '\t', '\'', "::" or ""(i.e
+	 string ended). */
+      /* Save restart for next time around.  */
+      p2 = p;
+      /* Restore argptr as it was on entry to this function.  */
+      *argptr = saved_arg2;
+      /* PASS1: at this point p->"::fun" argptr->"AAA::inA::fun".  */
+
+      /* All ready for next pass through the loop.  */
     }			/* while (1) */
 
   /* Last chance attempt -- check entire name as a symbol.  Use "copy"
@@ -1289,6 +1346,7 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
   copy[p - saved_arg2] = '\000';
   /* Set argptr to skip over the name.  */
   *argptr = (*p == '\'') ? p + 1 : p;
+
   /* Look up entire name */
   sym = lookup_symbol (copy, 0, VAR_DOMAIN, 0, &sym_symtab);
   if (sym)
@@ -1307,7 +1365,9 @@ decode_compound (char **argptr, int funfirstline, char ***canonical,
 /* Return the symbol corresponding to the substring of *ARGPTR ending
    at P, allowing whitespace.  Also, advance *ARGPTR past the symbol
    name in question, the compound object separator ("::" or "."), and
-   whitespace.  */
+   whitespace.  Note that *ARGPTR is changed whether or not the
+   lookup_symbol call finds anything (i.e we return NULL).  As an
+   example, say ARGPTR is "AAA::inA::fun" and P is "::inA::fun".  */
 
 static struct symbol *
 lookup_prefix_sym (char **argptr, char *p)
@@ -1323,12 +1383,15 @@ lookup_prefix_sym (char **argptr, char *p)
   memcpy (copy, *argptr, p - *argptr);
   copy[p - *argptr] = 0;
 
-  /* Discard the class name from the arg.  */
+  /* Discard the class name from the argptr.  */
   p = p1 + (p1[0] == ':' ? 2 : 1);
   while (*p == ' ' || *p == '\t')
     p++;
   *argptr = p;
 
+  /* At this point p1->"::inA::fun", p->"inA::fun" copy->"AAA",
+     argptr->"inA::fun" */
+
   return lookup_symbol (copy, 0, STRUCT_DOMAIN, 0,
 			(struct symtab **) NULL);
 }