diff --git a/gdb/symtab.c b/gdb/symtab.c
index 266cc94..021d538 100644
--- a/gdb/symtab.c
+++ b/gdb/symtab.c
@@ -71,7 +71,7 @@ static struct symbol *lookup_symbol_aux (const char *name,
 					 const struct block *block,
 					 const domain_enum domain,
 					 enum language language,
-					 struct field_of_this_result *is_a_field_of_this);
+					 struct field_of_this_result *);
 
 static
 struct symbol *lookup_symbol_aux_local (const char *name,
@@ -1291,16 +1291,9 @@ demangle_for_lookup (const char *name, enum language lang,
   return cleanup;
 }
 
-/* Find the definition for a specified symbol name NAME
-   in domain DOMAIN, visible from lexical block BLOCK.
-   Returns the struct symbol pointer, or zero if no symbol is found.
-   C++: if IS_A_FIELD_OF_THIS is nonzero on entry, check to see if
-   NAME is a field of the current implied argument `this'.  If so set
-   *IS_A_FIELD_OF_THIS to 1, otherwise set it to zero.
-   BLOCK_FOUND is set to the block in which NAME is found (in the case of
-   a field of `this', value_of_this sets BLOCK_FOUND to the proper value.)  */
+/* See symtab.h.
 
-/* This function (or rather its subordinates) have a bunch of loops and
+   This function (or rather its subordinates) have a bunch of loops and
    it would seem to be attractive to put in some QUIT's (though I'm not really
    sure whether it can run long enough to be really important).  But there
    are a few calls for which it would appear to be bad news to quit
@@ -1326,8 +1319,7 @@ lookup_symbol_in_language (const char *name, const struct block *block,
   return returnval;
 }
 
-/* Behave like lookup_symbol_in_language, but performed with the
-   current language.  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_symbol (const char *name, const struct block *block,
@@ -1339,8 +1331,7 @@ lookup_symbol (const char *name, const struct block *block,
 				    is_a_field_of_this);
 }
 
-/* Look up the `this' symbol for LANG in BLOCK.  Return the symbol if
-   found, or NULL if not found.  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_language_this (const struct language_defn *lang,
@@ -1483,10 +1474,7 @@ lookup_symbol_aux (const char *name, const struct block *block,
   return lookup_static_symbol_aux (name, domain);
 }
 
-/* Search all static file-level symbols for NAME from DOMAIN.  Do the symtabs
-   first, then check the psymtabs.  If a psymtab indicates the existence of the
-   desired name as a file-level static, then do psymtab-to-symtab conversion on
-   the fly and return the found symbol.  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_static_symbol_aux (const char *name, const domain_enum domain)
@@ -1549,7 +1537,7 @@ lookup_symbol_aux_local (const char *name, const struct block *block,
   return NULL;
 }
 
-/* Look up OBJFILE to BLOCK.  */
+/* See symtab.h.  */
 
 struct objfile *
 lookup_objfile_from_block (const struct block *block)
@@ -1574,8 +1562,7 @@ lookup_objfile_from_block (const struct block *block)
   return NULL;
 }
 
-/* Look up a symbol in a block; if found, fixup the symbol, and set
-   block_found appropriately.  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_symbol_aux_block (const char *name, const struct block *block,
@@ -1593,8 +1580,7 @@ lookup_symbol_aux_block (const char *name, const struct block *block,
   return NULL;
 }
 
-/* Check all global symbols in OBJFILE in symtabs and
-   psymtabs.  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_global_symbol_from_objfile (const struct objfile *main_objfile,
@@ -1765,9 +1751,7 @@ lookup_symbol_aux_quick (struct objfile *objfile, int kind,
   return fixup_symbol_section (sym, objfile);
 }
 
-/* A default version of lookup_symbol_nonlocal for use by languages
-   that can't think of anything better to do.  This implements the C
-   lookup rules.  */
+/* See symtab.h.  */
 
 struct symbol *
 basic_lookup_symbol_nonlocal (const char *name,
@@ -1811,8 +1795,7 @@ basic_lookup_symbol_nonlocal (const char *name,
   return lookup_symbol_global (name, block, domain);
 }
 
-/* Lookup a symbol in the static block associated to BLOCK, if there
-   is one; do nothing if BLOCK is NULL or a global block.  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_symbol_static (const char *name,
@@ -1867,8 +1850,7 @@ lookup_symbol_global_iterator_cb (struct objfile *objfile,
   return (data->result != NULL);
 }
 
-/* Lookup a symbol in all files' global blocks (searching psymtabs if
-   necessary).  */
+/* See symtab.h.  */
 
 struct symbol *
 lookup_symbol_global (const char *name,
@@ -1917,9 +1899,7 @@ symbol_matches_domain (enum language symbol_language,
   return (symbol_domain == domain);
 }
 
-/* Look up a type named NAME in the struct_domain.  The type returned
-   must not be opaque -- i.e., must have at least one field
-   defined.  */
+/* See symtab.h.  */
 
 struct type *
 lookup_transparent_type (const char *name)
@@ -1960,7 +1940,7 @@ basic_lookup_transparent_type_quick (struct objfile *objfile, int kind,
 /* The standard implementation of lookup_transparent_type.  This code
    was modeled on lookup_symbol -- the parts not relevant to looking
    up types were just left out.  In particular it's assumed here that
-   types are available in struct_domain and only at file-static or
+   types are available in STRUCT_DOMAIN and only in file-static or
    global blocks.  */
 
 struct type *
@@ -2030,7 +2010,7 @@ basic_lookup_transparent_type (const char *name)
   return (struct type *) 0;
 }
 
-/* Search BLOCK for symbol NAME in DOMAIN.
+/* See symtab.h.
 
    Note that if NAME is the demangled form of a C++ symbol, we will fail
    to find a match during the binary search of the non-encoded names, but
diff --git a/gdb/symtab.h b/gdb/symtab.h
index 4a47d48..9d1aa98 100644
--- a/gdb/symtab.h
+++ b/gdb/symtab.h
@@ -1043,13 +1043,22 @@ struct field_of_this_result
 
   struct field *field;
 
-  /* If the symbol was found as an function field of 'this', then this
+  /* If the symbol was found as a function field of 'this', then this
      is non-NULL and points to the particular field.  */
 
   struct fn_fieldlist *fn_field;
 };
 
-/* lookup a symbol by name (optional block) in language.  */
+/* Find the definition for a specified symbol name NAME
+   in domain DOMAIN in language LANGUAGE, visible from lexical block BLOCK
+   if non-NULL or from global/static blocks if BLOCK is NULL.
+   Returns the struct symbol pointer, or NULL if no symbol is found.
+   C++: if IS_A_FIELD_OF_THIS is non-NULL on entry, check to see if
+   NAME is a field of the current implied argument `this'.  If so fill in the
+   fields of IS_A_FIELD_OF_THIS, otherwise the fields are set to NULL.
+   BLOCK_FOUND is set to the block in which NAME is found (in the case of
+   a field of `this', value_of_this sets BLOCK_FOUND to the proper value).
+   The symbol's section is fixed up if necessary.  */
 
 extern struct symbol *lookup_symbol_in_language (const char *,
 						 const struct block *,
@@ -1057,15 +1066,15 @@ extern struct symbol *lookup_symbol_in_language (const char *,
 						 enum language,
 						 struct field_of_this_result *);
 
-/* lookup a symbol by name (optional block, optional symtab)
-   in the current language.  */
+/* Same as lookup_symbol_in_language, but using the current language.  */
 
 extern struct symbol *lookup_symbol (const char *, const struct block *,
 				     const domain_enum,
 				     struct field_of_this_result *);
 
 /* A default version of lookup_symbol_nonlocal for use by languages
-   that can't think of anything better to do.  */
+   that can't think of anything better to do.
+   This implements the C lookup rules.  */
 
 extern struct symbol *basic_lookup_symbol_nonlocal (const char *,
 						    const struct block *,
@@ -1075,42 +1084,49 @@ extern struct symbol *basic_lookup_symbol_nonlocal (const char *,
    lookup_symbol_nonlocal functions.  */
 
 /* Lookup a symbol in the static block associated to BLOCK, if there
-   is one; do nothing if BLOCK is NULL or a global block.  */
+   is one; do nothing if BLOCK is NULL or a global block.
+   Upon success sets BLOCK_FOUND and fixes up the symbol's section
+   if necessary.  */
 
 extern struct symbol *lookup_symbol_static (const char *name,
 					    const struct block *block,
 					    const domain_enum domain);
 
-/* Lookup a symbol in all files' global blocks (searching psymtabs if
-   necessary).  */
+/* Lookup a symbol in all files' global blocks.
+   Upon success sets BLOCK_FOUND and fixes up the symbol's section
+   if necessary.  */
 
 extern struct symbol *lookup_symbol_global (const char *name,
 					    const struct block *block,
 					    const domain_enum domain);
 
-/* Lookup a symbol within the block BLOCK.  This, unlike
-   lookup_symbol_block, will set SYMTAB and BLOCK_FOUND correctly, and
-   will fix up the symbol if necessary.  */
+/* Lookup a symbol within the block BLOCK.
+   Upon success sets BLOCK_FOUND and fixes up the symbol's section
+   if necessary.  */
 
 extern struct symbol *lookup_symbol_aux_block (const char *name,
 					       const struct block *block,
 					       const domain_enum domain);
 
+/* Look up the `this' symbol for LANG in BLOCK.  Return the symbol if
+   found, or NULL if not found.  */
+
 extern struct symbol *lookup_language_this (const struct language_defn *lang,
 					    const struct block *block);
 
-/* Lookup a symbol only in the file static scope of all the objfiles.  */
-
-struct symbol *lookup_static_symbol_aux (const char *name,
-					 const domain_enum domain);
+/* Search all static file-level symbols for NAME from DOMAIN.
+   Upon success sets BLOCK_FOUND and fixes up the symbol's section
+   if necessary.  */
 
+extern struct symbol *lookup_static_symbol_aux (const char *name,
+						const domain_enum domain);
 
-/* lookup a symbol by name, within a specified block.  */
+/* Search BLOCK for symbol NAME in DOMAIN.  */
 
 extern struct symbol *lookup_block_symbol (const struct block *, const char *,
 					   const domain_enum);
 
-/* lookup a [struct, union, enum] by name, within a specified block.  */
+/* Lookup a [struct, union, enum] by name, within a specified block.  */
 
 extern struct type *lookup_struct (const char *, const struct block *);
 
@@ -1157,9 +1173,13 @@ extern int find_pc_line_pc_range (CORE_ADDR, CORE_ADDR *, CORE_ADDR *);
 
 extern void reread_symbols (void);
 
+/* Look up a type named NAME in STRUCT_DOMAIN in the current language.
+   The type returned must not be opaque -- i.e., must have at least one field
+   defined.  */
+
 extern struct type *lookup_transparent_type (const char *);
-extern struct type *basic_lookup_transparent_type (const char *);
 
+extern struct type *basic_lookup_transparent_type (const char *);
 
 /* Macro for name of symbol to indicate a file compiled with gcc.  */
 #ifndef GCC_COMPILED_FLAG_SYMBOL
@@ -1369,10 +1389,16 @@ extern struct cleanup *make_cleanup_free_search_symbols (struct symbol_search
 extern /*const */ char *main_name (void);
 extern enum language main_language (void);
 
-/* Check global symbols in objfile.  */
-struct symbol *lookup_global_symbol_from_objfile (const struct objfile *,
-						  const char *name,
-						  const domain_enum domain);
+/* Lookup symbol NAME from DOMAIN in MAIN_OBJFILE's global blocks.
+   This searches MAIN_OBJFILE as well as any associated separate debug info
+   objfiles of MAIN_OBJFILE.
+   Upon success sets BLOCK_FOUND and fixes up the symbol's section
+   if necessary.  */
+
+extern struct symbol *
+  lookup_global_symbol_from_objfile (const struct objfile *main_objfile,
+				     const char *name,
+				     const domain_enum domain);
 
 /* Return 1 if the supplied producer string matches the ARM RealView
    compiler (armcc).  */
@@ -1381,6 +1407,8 @@ int producer_is_realview (const char *producer);
 void fixup_section (struct general_symbol_info *ginfo,
 		    CORE_ADDR addr, struct objfile *objfile);
 
+/* Look up objfile containing BLOCK.  */
+
 struct objfile *lookup_objfile_from_block (const struct block *block);
 
 extern unsigned int symtab_create_debug;
