Clean up some function comments in symtab.[ch].
authorDoug Evans <xdje42@gmail.com>
Sun, 26 Oct 2014 16:35:53 +0000 (09:35 -0700)
committerDoug Evans <xdje42@gmail.com>
Sun, 26 Oct 2014 16:35:53 +0000 (09:35 -0700)
gdb/ChangeLog:

* symtab.h (struct field_of_this_result): Fix typo in comment.
(lookup_symbol_in_language): Move function comment here.
(lookup_symbol): Improve function comment.
(basic_lookup_symbol_nonlocal): Ditto.
(lookup_symbol_static, lookup_symbol_global): Ditto.
(lookup_symbol_aux_block): Ditto.
(lookup_language_this): Add function comment.
(lookup_static_symbol_aux): Explicitly mark as extern.  Improve
function comment.
(lookup_block_symbol): Improve function comment.
(lookup_struct): Fix capitalization in function comment.
(lookup_transparent_type): Add function comment.
(lookup_global_symbol_from_objfile): Explicitly mark as extern.
Improve function comment.
(lookup_objfile_from_block): Add function comment.
* symtab.c (lookup_symbol_in_language): Update function comment.
(lookup_symbol, lookup_language_this): Ditto.
(lookup_static_symbol_aux, lookup_objfile_from_block): Ditto.
(lookup_symbol_aux_block, lookup_global_symbol_from_objfile): Ditto.
(basic_lookup_symbol_nonlocal): Ditto.
(lookup_symbol_static, lookup_symbol_global): Ditto.
(lookup_transparent_type, lookup_block_symbol): Ditto.

gdb/ChangeLog
gdb/symtab.c
gdb/symtab.h

index 1ff55a67284a0eff59fd4ce7452459e88e15bc7c..62c015d0145919ff3cf4f6f3735d1be19d8cb00a 100644 (file)
@@ -1,3 +1,28 @@
+2014-10-26  Doug Evans  <xdje42@gmail.com>
+
+       * symtab.h (struct field_of_this_result): Fix typo in comment.
+       (lookup_symbol_in_language): Move function comment here.
+       (lookup_symbol): Improve function comment.
+       (basic_lookup_symbol_nonlocal): Ditto.
+       (lookup_symbol_static, lookup_symbol_global): Ditto.
+       (lookup_symbol_aux_block): Ditto.
+       (lookup_language_this): Add function comment.
+       (lookup_static_symbol_aux): Explicitly mark as extern.  Improve
+       function comment.
+       (lookup_block_symbol): Improve function comment.
+       (lookup_struct): Fix capitalization in function comment.
+       (lookup_transparent_type): Add function comment.
+       (lookup_global_symbol_from_objfile): Explicitly mark as extern.
+       Improve function comment.
+       (lookup_objfile_from_block): Add function comment.
+       * symtab.c (lookup_symbol_in_language): Update function comment.
+       (lookup_symbol, lookup_language_this): Ditto.
+       (lookup_static_symbol_aux, lookup_objfile_from_block): Ditto.
+       (lookup_symbol_aux_block, lookup_global_symbol_from_objfile): Ditto.
+       (basic_lookup_symbol_nonlocal): Ditto.
+       (lookup_symbol_static, lookup_symbol_global): Ditto.
+       (lookup_transparent_type, lookup_block_symbol): Ditto.
+
 2014-10-25  Doug Evans  <xdje42@gmail.com>
 
        * symtab.c (types_info): Delete forward decl.
index 266cc941c05748e9ca83b77a6c5cefa5035b00b2..021d538360850ce9920a4503391ffd028fe5ec38 100644 (file)
@@ -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
index 4a47d48d5354e184c01b1f71da635a8c9eeac36b..9d1aa98ea22d6aa0c98bba52c4bee51aa97556d8 100644 (file)
@@ -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;