[commit] symtab.c (iterate_over_some_symtabs): Add comment.

[Doug Evans <dje at google dot com>]

Hi.

This assert in iterate_over_some_symtabs bothered me.

      if (real_path != NULL)
	{
	  ...
	  gdb_assert (IS_ABSOLUTE_PATH (name));
	}

There's nothing in the function's documentation that says
NAME has to be an absolute path.
However, reviewing all the callers shows it will indeed always
be an absolute path if REAL_PATH is non-NULL.  It basically comes from
this in symfile.h:

  /* Expand and iterate over each "partial" symbol table in OBJFILE
     where the source file is named NAME.

     If NAME is not absolute, a match after a '/' in the symbol table's
     file name will also work, REAL_PATH is NULL then.  If NAME is
     absolute then REAL_PATH is non-NULL absolute file name as resolved
     via gdb_realpath from NAME.

     If a match is found, the "partial" symbol table is expanded.
     Then, this calls iterate_over_some_symtabs (or equivalent) over
     all newly-created symbol tables, passing CALLBACK and DATA to it.
     The result of this call is returned.  */
  int (*map_symtabs_matching_filename) (struct objfile *objfile,
					const char *name,
					const char *real_path,
					int (*callback) (struct symtab *,
							 void *),
					void *data);

To remove the confusion I added this comment.
Committed.

2013-07-29  Doug Evans  <dje@google.com>

	* symtab.c (iterate_over_some_symtabs): Add comment.

Index: symtab.c
===================================================================
RCS file: /cvs/src/src/gdb/symtab.c,v
retrieving revision 1.363
diff -u -p -r1.363 symtab.c
--- symtab.c	29 Jul 2013 20:04:16 -0000	1.363
+++ symtab.c	29 Jul 2013 20:14:47 -0000
@@ -186,6 +186,9 @@ compare_filenames_for_search (const char
 /* Check for a symtab of a specific name by searching some symtabs.
    This is a helper function for callbacks of iterate_over_symtabs.
 
+   If NAME is not absolute, then REAL_PATH is NULL
+   If NAME is absolute, then REAL_PATH is the gdb_realpath form of NAME.
+
    The return value, NAME, REAL_PATH, CALLBACK, and DATA
    are identical to the `map_symtabs_matching_filename' method of
    quick_symbol_functions.
@@ -230,7 +233,6 @@ iterate_over_some_symtabs (const char *n
 
       /* If the user gave us an absolute path, try to find the file in
 	 this symtab and use its absolute path.  */
-
       if (real_path != NULL)
 	{
 	  const char *fullname = symtab_to_fullname (s);