2011-08-09 Pedro Alves <pedro@codesourcery.com>

	gdb/
	* elfread.c (elf_symtab_read): Ditto.
	* maint.c (maintenance_command): Ditto.
	* somread.c (som_symtab_read): Ditto.
	* solib.c (solib_find, solib_map_sections, update_solib_list)
	(solib_add, info_sharedlibrary_command, solib_name_from_address)
	(solib_create_inferior_hook, in_solib_dynsym_resolve_code)
	(sharedlibrary_command, no_shared_libraries): Rework comments.
	* solib-irix.c (locate_base, disable_break, enable_break)
	(irix_solib_create_inferior_hook, irix_solib_create_inferior_hook)
	(irix_current_sos, irix_open_symbol_file_object)
	(irix_special_symbol_handling): Ditto.
	* solib-sunos.c (locate_base, first_link_map_member)
	(sunos_current_sos, disable_break, enable_break)
	(sunos_special_symbol_handling, sunos_solib_create_inferior_hook):
	Ditto.
	* solib-svr4.c (bfd_lookup_symbol, elf_locate_base, locate_base)
	(open_symbol_file_object, svr4_current_sos, enable_break)
	(svr4_special_symbol_handling, svr4_solib_create_inferior_hook):
	Ditto.
	* solib-frv.c (bfd_lookup_symbol, open_symbol_file_object)
	(frv_current_sos, enable_break, frv_special_symbol_handling)
	(frv_solib_create_inferior_hook): Ditto.
	* solist.h (struct target_so_ops): Extend the comments of the
	special_symbol_handling, current_sos and open_symbol_file_object
	methods.

10 files changed, 150 insertions, 692 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index ac421f1782a..339c2d16ca0 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,31 @@
+2011-08-09  Pedro Alves  <pedro@codesourcery.com>
+
+	* elfread.c (elf_symtab_read): Ditto.
+	* maint.c (maintenance_command): Ditto.
+	* somread.c (som_symtab_read): Ditto.
+	* solib.c (solib_find, solib_map_sections, update_solib_list)
+	(solib_add, info_sharedlibrary_command, solib_name_from_address)
+	(solib_create_inferior_hook, in_solib_dynsym_resolve_code)
+	(sharedlibrary_command, no_shared_libraries): Rework comments.
+	* solib-irix.c (locate_base, disable_break, enable_break)
+	(irix_solib_create_inferior_hook, irix_solib_create_inferior_hook)
+	(irix_current_sos, irix_open_symbol_file_object)
+	(irix_special_symbol_handling): Ditto.
+	* solib-sunos.c (locate_base, first_link_map_member)
+	(sunos_current_sos, disable_break, enable_break)
+	(sunos_special_symbol_handling, sunos_solib_create_inferior_hook):
+	Ditto.
+	* solib-svr4.c (bfd_lookup_symbol, elf_locate_base, locate_base)
+	(open_symbol_file_object, svr4_current_sos, enable_break)
+	(svr4_special_symbol_handling, svr4_solib_create_inferior_hook):
+	Ditto.
+	* solib-frv.c (bfd_lookup_symbol, open_symbol_file_object)
+	(frv_current_sos, enable_break, frv_special_symbol_handling)
+	(frv_solib_create_inferior_hook): Ditto.
+	* solist.h (struct target_so_ops): Extend the comments of the
+	special_symbol_handling, current_sos and open_symbol_file_object
+	methods.
+
 2011-08-09  Phil Muldoon  <pmuldoon@redhat.com>
 
 	* python/lib/gdb/__init__.py: Auto-load files in command and
diff --git a/gdb/elfread.c b/gdb/elfread.c
index 998a96e5b3e..a309a2cc1b6 100644
--- a/gdb/elfread.c
+++ b/gdb/elfread.c
@@ -206,18 +206,7 @@ record_minimal_symbol (const char *name, int name_len, int copy_name,
 					  bfd_section, objfile);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   elf_symtab_read -- read the symbol table of an ELF file
-
-   SYNOPSIS
-
-   void elf_symtab_read (struct objfile *objfile, int type,
-			 long number_of_symbols, asymbol **symbol_table)
-
-   DESCRIPTION
+/* Read the symbol table of an ELF file.
 
    Given an objfile, a symbol table, and a flag indicating whether the
    symbol table contains regular, dynamic, or synthetic symbols, add all
@@ -227,9 +216,7 @@ record_minimal_symbol (const char *name, int name_len, int copy_name,
    defined in the ELF symbol table, which can be used to locate
    the beginnings of sections from each ".o" file that was linked to
    form the executable objfile.  We gather any such info and record it
-   in data structures hung off the objfile's private data.
-
- */
+   in data structures hung off the objfile's private data.  */
 
 #define ST_REGULAR 0
 #define ST_DYNAMIC 1
diff --git a/gdb/maint.c b/gdb/maint.c
index ca9b3cca643..b33e94f0ade 100644
--- a/gdb/maint.c
+++ b/gdb/maint.c
@@ -74,19 +74,7 @@ show_watchdog (struct ui_file *file, int from_tty,
   fprintf_filtered (file, _("Watchdog timer is %s.\n"), value);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   maintenance_command -- access the maintenance subcommands
-
-   SYNOPSIS
-
-   void maintenance_command (char *args, int from_tty)
-
-   DESCRIPTION
-
- */
+/* Access the maintenance subcommands.  */
 
 static void
 maintenance_command (char *args, int from_tty)
diff --git a/gdb/solib-frv.c b/gdb/solib-frv.c
index 7299cefc00d..e1c16d92b14 100644
--- a/gdb/solib-frv.c
+++ b/gdb/solib-frv.c
@@ -239,17 +239,7 @@ static void frv_relocate_main_executable (void);
 static CORE_ADDR main_got (void);
 static int enable_break2 (void);
 
-/*
-
-   LOCAL FUNCTION
-
-   bfd_lookup_symbol -- lookup the value for a specific symbol
-
-   SYNOPSIS
-
-   CORE_ADDR bfd_lookup_symbol (bfd *abfd, char *symname)
-
-   DESCRIPTION
+/* Lookup the value for a specific symbol.
 
    An expensive way to lookup the value of a single symbol for
    bfd's that are only temporary anyway.  This is used by the
@@ -257,8 +247,7 @@ static int enable_break2 (void);
    interface structures in the shared library.
 
    Note that 0 is specifically allowed as an error return (no
-   such symbol).
- */
+   such symbol).  */
 
 static CORE_ADDR
 bfd_lookup_symbol (bfd *abfd, char *symname)
@@ -321,26 +310,7 @@ bfd_lookup_symbol (bfd *abfd, char *symname)
   return symaddr;
 }
 
-
-/*
-
-  LOCAL FUNCTION
-
-  open_symbol_file_object
-
-  SYNOPSIS
-
-  void open_symbol_file_object (void *from_tty)
-
-  DESCRIPTION
-
-  If no open symbol file, attempt to locate and open the main symbol
-  file.
-
-  If FROM_TTYP dereferences to a non-zero integer, allow messages to
-  be printed.  This parameter is a pointer rather than an int because
-  open_symbol_file_object() is called via catch_errors() and
-  catch_errors() requires a pointer argument.  */
+/* Implement the "open_symbol_file_object" target_so_ops method.  */
 
 static int
 open_symbol_file_object (void *from_ttyp)
@@ -413,24 +383,7 @@ lm_base (void)
 }
 
 
-/* LOCAL FUNCTION
-
-   frv_current_sos -- build a list of currently loaded shared objects
-
-   SYNOPSIS
-
-   struct so_list *frv_current_sos ()
-
-   DESCRIPTION
-
-   Build a list of `struct so_list' objects describing the shared
-   objects currently loaded in the inferior.  This list does not
-   include an entry for the main executable file.
-
-   Note that we only gather information directly available from the
-   inferior --- we don't examine any of the shared library files
-   themselves.  The declaration of `struct so_list' says which fields
-   we provide values for.  */
+/* Implement the "current_sos" target_so_ops method.  */
 
 static struct so_list *
 frv_current_sos (void)
@@ -601,17 +554,7 @@ enable_break_failure_warning (void)
 	   "and track explicitly loaded dynamic code."));
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   enable_break -- arrange for dynamic linker to hit breakpoint
-
-   SYNOPSIS
-
-   int enable_break (void)
-
-   DESCRIPTION
+/* Arrange for dynamic linker to hit breakpoint.
 
    The dynamic linkers has, as part of its debugger interface, support
    for arranging for the inferior to hit a breakpoint after mapping in
@@ -631,9 +574,7 @@ enable_break_failure_warning (void)
    using the interpreter's loadmap.  Once the relocated address
    is known, we fetch the value (address) corresponding to r_brk
    and then use that value to fetch the entry point of the function
-   we're interested in.
-
- */
+   we're interested in.  */
 
 static int enable_break2_done = 0;
 
@@ -884,28 +825,12 @@ enable_break (void)
   return 1;
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   special_symbol_handling -- additional shared library symbol handling
-
-   SYNOPSIS
-
-   void special_symbol_handling ()
-
-   DESCRIPTION
-
-   Once the symbols from a shared object have been loaded in the usual
-   way, we are called to do any system specific symbol handling that 
-   is needed.
-
- */
+/* Implement the "special_symbol_handling" target_so_ops method.  */
 
 static void
 frv_special_symbol_handling (void)
 {
-  /* Nothing needed (yet) for FRV.  */
+  /* Nothing needed for FRV.  */
 }
 
 static void
@@ -983,27 +908,11 @@ frv_relocate_main_executable (void)
   main_executable_lm_info->got_value = main_got ();
 }
 
-/*
-
-   GLOBAL FUNCTION
-
-   frv_solib_create_inferior_hook -- shared library startup support
-
-   SYNOPSIS
-
-   void frv_solib_create_inferior_hook ()
-
-   DESCRIPTION
-
-   When gdb starts up the inferior, it nurses it along (through the
-   shell) until it is ready to execute it's first instruction.  At this
-   point, this function gets called via expansion of the macro
-   SOLIB_CREATE_INFERIOR_HOOK.
+/* Implement the "create_inferior_hook" target_solib_ops method.
 
-   For the FR-V shared library ABI (FDPIC), the main executable
-   needs to be relocated.  The shared library breakpoints also need
-   to be enabled.
- */
+   For the FR-V shared library ABI (FDPIC), the main executable needs
+   to be relocated.  The shared library breakpoints also need to be
+   enabled.  */
 
 static void
 frv_solib_create_inferior_hook (int from_tty)
diff --git a/gdb/solib-irix.c b/gdb/solib-irix.c
index 7bb528a8723..7e3c4087516 100644
--- a/gdb/solib-irix.c
+++ b/gdb/solib-irix.c
@@ -244,17 +244,7 @@ static void *base_breakpoint;
 
 static CORE_ADDR debug_base;	/* Base of dynamic linker structures.  */
 
-/*
-
-   LOCAL FUNCTION
-
-   locate_base -- locate the base address of dynamic linker structs
-
-   SYNOPSIS
-
-   CORE_ADDR locate_base (void)
-
-   DESCRIPTION
+/* Locate the base address of dynamic linker structs.
 
    For both the SunOS and SVR4 shared library implementations, if the
    inferior executable has been linked dynamically, there is a single
@@ -287,9 +277,7 @@ static CORE_ADDR debug_base;	/* Base of dynamic linker structures.  */
    we need to find this address.  We may be stopped on the first instruc-
    tion of the interpreter (C shared library), the first instruction of
    the executable itself, or somewhere else entirely (if we attached
-   to the process for example).
-
- */
+   to the process for example).  */
 
 static CORE_ADDR
 locate_base (void)
@@ -305,22 +293,10 @@ locate_base (void)
   return (address);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   disable_break -- remove the "mapping changed" breakpoint
-
-   SYNOPSIS
-
-   static int disable_break ()
-
-   DESCRIPTION
+/* Remove the "mapping changed" breakpoint.
 
    Removes the breakpoint that gets hit when the dynamic linker
-   completes a mapping change.
-
- */
+   completes a mapping change.  */
 
 static int
 disable_break (void)
@@ -346,21 +322,10 @@ disable_break (void)
   return (status);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   enable_break -- arrange for dynamic linker to hit breakpoint
-
-   SYNOPSIS
-
-   int enable_break (void)
-
-   DESCRIPTION
+/* Arrange for dynamic linker to hit breakpoint.
 
    This functions inserts a breakpoint at the entry point of the
-   main executable, where all shared libraries are mapped in.
- */
+   main executable, where all shared libraries are mapped in.  */
 
 static int
 enable_break (void)
@@ -384,22 +349,7 @@ enable_break (void)
   return 0;
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   irix_solib_create_inferior_hook -- shared library startup support
-
-   SYNOPSIS
-
-   void solib_create_inferior_hook (int from_tty)
-
-   DESCRIPTION
-
-   When gdb starts up the inferior, it nurses it along (through the
-   shell) until it is ready to execute it's first instruction.  At this
-   point, this function gets called via expansion of the macro
-   SOLIB_CREATE_INFERIOR_HOOK.
+/* Implement the "create_inferior_hook" target_solib_ops method.
 
    For SunOS executables, this first instruction is typically the
    one at "_start", or a similar text label, regardless of whether
@@ -433,8 +383,7 @@ enable_break (void)
    handling will probably have to wait until the implementation is
    changed to use the "breakpoint handler function" method.
 
-   Also, what if child has exit()ed?  Must exit loop somehow.
- */
+   Also, what if child has exit()ed?  Must exit loop somehow.  */
 
 static void
 irix_solib_create_inferior_hook (int from_tty)
@@ -499,24 +448,7 @@ irix_solib_create_inferior_hook (int from_tty)
   inf->control.stop_soon = NO_STOP_QUIETLY;
 }
 
-/* LOCAL FUNCTION
-
-   current_sos -- build a list of currently loaded shared objects
-
-   SYNOPSIS
-
-   struct so_list *current_sos ()
-
-   DESCRIPTION
-
-   Build a list of `struct so_list' objects describing the shared
-   objects currently loaded in the inferior.  This list does not
-   include an entry for the main executable file.
-
-   Note that we only gather information directly available from the
-   inferior --- we don't examine any of the shared library files
-   themselves.  The declaration of `struct so_list' says which fields
-   we provide values for.  */
+/* Implement the "current_sos" target_so_ops method.  */
 
 static struct so_list *
 irix_current_sos (void)
@@ -603,27 +535,12 @@ irix_current_sos (void)
   return head;
 }
 
-/*
-
-  LOCAL FUNCTION
-
-  irix_open_symbol_file_object
-
-  SYNOPSIS
-
-  void irix_open_symbol_file_object (void *from_tty)
+/* Implement the "open_symbol_file_object" target_so_ops method.
 
-  DESCRIPTION
-
-  If no open symbol file, attempt to locate and open the main symbol
-  file.  On IRIX, this is the first link map entry.  If its name is
-  here, we can open it.  Useful when attaching to a process without
-  first loading its symbol file.
-
-  If FROM_TTYP dereferences to a non-zero integer, allow messages to
-  be printed.  This parameter is a pointer rather than an int because
-  open_symbol_file_object() is called via catch_errors() and
-  catch_errors() requires a pointer argument.  */
+   If no open symbol file, attempt to locate and open the main symbol
+   file.  On IRIX, this is the first link map entry.  If its name is
+   here, we can open it.  Useful when attaching to a process without
+   first loading its symbol file.  */
 
 static int
 irix_open_symbol_file_object (void *from_ttyp)
@@ -676,31 +593,9 @@ irix_open_symbol_file_object (void *from_ttyp)
   return 1;
 }
 
+/* Implement the "special_symbol_handling" target_so_ops method.
 
-/*
-
-   LOCAL FUNCTION
-
-   irix_special_symbol_handling -- additional shared library symbol handling
-
-   SYNOPSIS
-
-   void irix_special_symbol_handling ()
-
-   DESCRIPTION
-
-   Once the symbols from a shared object have been loaded in the usual
-   way, we are called to do any system specific symbol handling that 
-   is needed.
-
-   For SunOS4, this consisted of grunging around in the dynamic
-   linkers structures to find symbol definitions for "common" symbols
-   and adding them to the minimal symbol table for the runtime common
-   objfile.
-
-   However, for IRIX, there's nothing to do.
-
- */
+   For IRIX, there's nothing to do.  */
 
 static void
 irix_special_symbol_handling (void)
diff --git a/gdb/solib-sunos.c b/gdb/solib-sunos.c
index 9936038d4e5..405ca4f7192 100644
--- a/gdb/solib-sunos.c
+++ b/gdb/solib-sunos.c
@@ -274,17 +274,7 @@ solib_add_common_symbols (CORE_ADDR rtc_symp)
 }
 
 
-/*
-
-   LOCAL FUNCTION
-
-   locate_base -- locate the base address of dynamic linker structs
-
-   SYNOPSIS
-
-   CORE_ADDR locate_base (void)
-
-   DESCRIPTION
+/* Locate the base address of dynamic linker structs.
 
    For both the SunOS and SVR4 shared library implementations, if the
    inferior executable has been linked dynamically, there is a single
@@ -307,9 +297,7 @@ solib_add_common_symbols (CORE_ADDR rtc_symp)
    to a lot more work to discover the address of the debug base symbol.
    Because of this complexity, we cache the value we find and return that
    value on subsequent invocations.  Note there is no copy in the
-   executable symbol tables.
-
- */
+   executable symbol tables.  */
 
 static CORE_ADDR
 locate_base (void)
@@ -334,17 +322,7 @@ locate_base (void)
   return (0);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   first_link_map_member -- locate first member in dynamic linker's map
-
-   SYNOPSIS
-
-   static CORE_ADDR first_link_map_member (void)
-
-   DESCRIPTION
+/* Locate first member in dynamic linker's map.
 
    Find the first element in the inferior's dynamic link map, and
    return its address in the inferior.  This function doesn't copy the
@@ -375,24 +353,7 @@ open_symbol_file_object (void *from_ttyp)
 }
 
 
-/* LOCAL FUNCTION
-
-   current_sos -- build a list of currently loaded shared objects
-
-   SYNOPSIS
-
-   struct so_list *current_sos ()
-
-   DESCRIPTION
-
-   Build a list of `struct so_list' objects describing the shared
-   objects currently loaded in the inferior.  This list does not
-   include an entry for the main executable file.
-
-   Note that we only gather information directly available from the
-   inferior --- we don't examine any of the shared library files
-   themselves.  The declaration of `struct so_list' says which fields
-   we provide values for.  */
+/* Implement the "current_sos" target_so_ops method.  */
 
 static struct so_list *
 sunos_current_sos (void)
@@ -495,22 +456,10 @@ sunos_in_dynsym_resolve_code (CORE_ADDR pc)
   return 0;
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   disable_break -- remove the "mapping changed" breakpoint
-
-   SYNOPSIS
-
-   static int disable_break ()
-
-   DESCRIPTION
+/* Remove the "mapping changed" breakpoint.
 
    Removes the breakpoint that gets hit when the dynamic linker
-   completes a mapping change.
-
- */
+   completes a mapping change.  */
 
 static int
 disable_break (void)
@@ -547,18 +496,7 @@ disable_break (void)
   return 1;
 }
 
-
-/*
-
-   LOCAL FUNCTION
-
-   enable_break -- arrange for dynamic linker to hit breakpoint
-
-   SYNOPSIS
-
-   int enable_break (void)
-
-   DESCRIPTION
+/* Arrange for dynamic linker to hit breakpoint.
 
    Both the SunOS and the SVR4 dynamic linkers have, as part of their
    debugger interface, support for arranging for the inferior to hit
@@ -587,9 +525,9 @@ disable_break (void)
 
    The debugger interface structure also contains an enumeration which
    is set to either RT_ADD or RT_DELETE prior to changing the mapping,
-   depending upon whether or not the library is being mapped or unmapped,
-   and then set to RT_CONSISTENT after the library is mapped/unmapped.
- */
+   depending upon whether or not the library is being mapped or
+   unmapped, and then set to RT_CONSISTENT after the library is
+   mapped/unmapped.  */
 
 static int
 enable_break (void)
@@ -626,28 +564,12 @@ enable_break (void)
   return (success);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   special_symbol_handling -- additional shared library symbol handling
-
-   SYNOPSIS
-
-   void special_symbol_handling ()
-
-   DESCRIPTION
-
-   Once the symbols from a shared object have been loaded in the usual
-   way, we are called to do any system specific symbol handling that 
-   is needed.
+/* Implement the "special_symbol_handling" target_so_ops method.
 
    For SunOS4, this consists of grunging around in the dynamic
    linkers structures to find symbol definitions for "common" symbols
    and adding them to the minimal symbol table for the runtime common
-   objfile.
-
- */
+   objfile.  */
 
 static void
 sunos_special_symbol_handling (void)
@@ -689,22 +611,7 @@ sunos_special_symbol_handling (void)
     }
 }
 
-/*
-
-   GLOBAL FUNCTION
-
-   sunos_solib_create_inferior_hook -- shared library startup support
-
-   SYNOPSIS
-
-   void sunos_solib_create_inferior_hook ()
-
-   DESCRIPTION
-
-   When gdb starts up the inferior, it nurses it along (through the
-   shell) until it is ready to execute it's first instruction.  At this
-   point, this function gets called via expansion of the macro
-   SOLIB_CREATE_INFERIOR_HOOK.
+/* Implement the "create_inferior_hook" target_solib_ops method.
 
    For SunOS executables, this first instruction is typically the
    one at "_start", or a similar text label, regardless of whether
@@ -712,19 +619,9 @@ sunos_special_symbol_handling (void)
    startup code takes care of dynamically linking in any shared
    libraries, once gdb allows the inferior to continue.
 
-   For SVR4 executables, this first instruction is either the first
-   instruction in the dynamic linker (for dynamically linked
-   executables) or the instruction at "start" for statically linked
-   executables.  For dynamically linked executables, the system
-   first exec's /lib/libc.so.N, which contains the dynamic linker,
-   and starts it running.  The dynamic linker maps in any needed
-   shared libraries, maps in the actual user executable, and then
-   jumps to "start" in the user executable.
-
-   For both SunOS shared libraries, and SVR4 shared libraries, we
-   can arrange to cooperate with the dynamic linker to discover the
-   names of shared libraries that are dynamically linked, and the
-   base addresses to which they are linked.
+   We can arrange to cooperate with the dynamic linker to discover the
+   names of shared libraries that are dynamically linked, and the base
+   addresses to which they are linked.
 
    This function is responsible for discovering those names and
    addresses, and saving sufficient information about them to allow
@@ -738,8 +635,7 @@ sunos_special_symbol_handling (void)
    handling will probably have to wait until the implementation is
    changed to use the "breakpoint handler function" method.
 
-   Also, what if child has exit()ed?  Must exit loop somehow.
- */
+   Also, what if child has exit()ed?  Must exit loop somehow.  */
 
 static void
 sunos_solib_create_inferior_hook (int from_tty)
diff --git a/gdb/solib-svr4.c b/gdb/solib-svr4.c
index dffc62131ba..f643a2475bd 100644
--- a/gdb/solib-svr4.c
+++ b/gdb/solib-svr4.c
@@ -370,17 +370,7 @@ get_svr4_info (void)
 
 static int match_main (const char *);
 
-/*
-
-   LOCAL FUNCTION
-
-   bfd_lookup_symbol -- lookup the value for a specific symbol
-
-   SYNOPSIS
-
-   CORE_ADDR bfd_lookup_symbol (bfd *abfd, char *symname)
-
-   DESCRIPTION
+/* Lookup the value for a specific symbol.
 
    An expensive way to lookup the value of a single symbol for
    bfd's that are only temporary anyway.  This is used by the
@@ -392,8 +382,7 @@ static int match_main (const char *);
    if this architecture uses function descriptors.
 
    Note that 0 is specifically allowed as an error return (no
-   such symbol).
- */
+   such symbol).  */
 
 static CORE_ADDR
 bfd_lookup_symbol (bfd *abfd, const char *symname)
@@ -764,19 +753,8 @@ scan_dyntag_auxv (int dyntag, CORE_ADDR *ptr)
   return 0;
 }
 
-
-/*
-
-   LOCAL FUNCTION
-
-   elf_locate_base -- locate the base address of dynamic linker structs
-   for SVR4 elf targets.
-
-   SYNOPSIS
-
-   CORE_ADDR elf_locate_base (void)
-
-   DESCRIPTION
+/* Locate the base address of dynamic linker structs for SVR4 elf
+   targets.
 
    For SVR4 elf targets the address of the dynamic linker's runtime
    structure is contained within the dynamic info section in the
@@ -785,9 +763,7 @@ scan_dyntag_auxv (int dyntag, CORE_ADDR *ptr)
    real address before starting the inferior, we have to read in the
    dynamic info section from the inferior address space.
    If there are any errors while trying to find the address, we
-   silently return 0, otherwise the found address is returned.
-
- */
+   silently return 0, otherwise the found address is returned.  */
 
 static CORE_ADDR
 elf_locate_base (void)
@@ -828,17 +804,7 @@ elf_locate_base (void)
   return 0;
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   locate_base -- locate the base address of dynamic linker structs
-
-   SYNOPSIS
-
-   CORE_ADDR locate_base (struct svr4_info *)
-
-   DESCRIPTION
+/* Locate the base address of dynamic linker structs.
 
    For both the SunOS and SVR4 shared library implementations, if the
    inferior executable has been linked dynamically, there is a single
@@ -861,9 +827,7 @@ elf_locate_base (void)
    to a lot more work to discover the address of the debug base symbol.
    Because of this complexity, we cache the value we find and return that
    value on subsequent invocations.  Note there is no copy in the
-   executable symbol tables.
-
- */
+   executable symbol tables.  */
 
 static CORE_ADDR
 locate_base (struct svr4_info *info)
@@ -983,27 +947,12 @@ svr4_keep_data_in_core (CORE_ADDR vaddr, unsigned long size)
   return (name_lm >= vaddr && name_lm < vaddr + size);
 }
 
-/*
-
-  LOCAL FUNCTION
-
-  open_symbol_file_object
+/* Implement the "open_symbol_file_object" target_so_ops method.
 
-  SYNOPSIS
-
-  void open_symbol_file_object (void *from_tty)
-
-  DESCRIPTION
-
-  If no open symbol file, attempt to locate and open the main symbol
-  file.  On SVR4 systems, this is the first link map entry.  If its
-  name is here, we can open it.  Useful when attaching to a process
-  without first loading its symbol file.
-
-  If FROM_TTYP dereferences to a non-zero integer, allow messages to
-  be printed.  This parameter is a pointer rather than an int because
-  open_symbol_file_object() is called via catch_errors() and
-  catch_errors() requires a pointer argument.  */
+   If no open symbol file, attempt to locate and open the main symbol
+   file.  On SVR4 systems, this is the first link map entry.  If its
+   name is here, we can open it.  Useful when attaching to a process
+   without first loading its symbol file.  */
 
 static int
 open_symbol_file_object (void *from_ttyp)
@@ -1108,24 +1057,7 @@ svr4_default_sos (void)
   return head;
 }
 
-/* LOCAL FUNCTION
-
-   current_sos -- build a list of currently loaded shared objects
-
-   SYNOPSIS
-
-   struct so_list *current_sos ()
-
-   DESCRIPTION
-
-   Build a list of `struct so_list' objects describing the shared
-   objects currently loaded in the inferior.  This list does not
-   include an entry for the main executable file.
-
-   Note that we only gather information directly available from the
-   inferior --- we don't examine any of the shared library files
-   themselves.  The declaration of `struct so_list' says which fields
-   we provide values for.  */
+/* Implement the "current_sos" target_so_ops method.  */
 
 static struct so_list *
 svr4_current_sos (void)
@@ -1321,17 +1253,7 @@ exec_entry_point (struct bfd *abfd, struct target_ops *targ)
 					     targ);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   enable_break -- arrange for dynamic linker to hit breakpoint
-
-   SYNOPSIS
-
-   int enable_break (void)
-
-   DESCRIPTION
+/* Arrange for dynamic linker to hit breakpoint.
 
    Both the SunOS and the SVR4 dynamic linkers have, as part of their
    debugger interface, support for arranging for the inferior to hit
@@ -1361,8 +1283,7 @@ exec_entry_point (struct bfd *abfd, struct target_ops *targ)
    The debugger interface structure also contains an enumeration which
    is set to either RT_ADD or RT_DELETE prior to changing the mapping,
    depending upon whether or not the library is being mapped or unmapped,
-   and then set to RT_CONSISTENT after the library is mapped/unmapped.
- */
+   and then set to RT_CONSISTENT after the library is mapped/unmapped.  */
 
 static int
 enable_break (struct svr4_info *info, int from_tty)
@@ -1649,34 +1570,12 @@ enable_break (struct svr4_info *info, int from_tty)
   return 0;
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   special_symbol_handling -- additional shared library symbol handling
-
-   SYNOPSIS
-
-   void special_symbol_handling ()
-
-   DESCRIPTION
-
-   Once the symbols from a shared object have been loaded in the usual
-   way, we are called to do any system specific symbol handling that
-   is needed.
-
-   For SunOS4, this consisted of grunging around in the dynamic
-   linkers structures to find symbol definitions for "common" symbols
-   and adding them to the minimal symbol table for the runtime common
-   objfile.
-
-   However, for SVR4, there's nothing to do.
-
- */
+/* Implement the "special_symbol_handling" target_so_ops method.  */
 
 static void
 svr4_special_symbol_handling (void)
 {
+  /* Nothing to do.  */
 }
 
 /* Read the ELF program headers from ABFD.  Return the contents and
@@ -2133,28 +2032,7 @@ svr4_relocate_main_executable (void)
     }
 }
 
-/*
-
-   GLOBAL FUNCTION
-
-   svr4_solib_create_inferior_hook -- shared library startup support
-
-   SYNOPSIS
-
-   void svr4_solib_create_inferior_hook (int from_tty)
-
-   DESCRIPTION
-
-   When gdb starts up the inferior, it nurses it along (through the
-   shell) until it is ready to execute it's first instruction.  At this
-   point, this function gets called via expansion of the macro
-   SOLIB_CREATE_INFERIOR_HOOK.
-
-   For SunOS executables, this first instruction is typically the
-   one at "_start", or a similar text label, regardless of whether
-   the executable is statically or dynamically linked.  The runtime
-   startup code takes care of dynamically linking in any shared
-   libraries, once gdb allows the inferior to continue.
+/* Implement the "create_inferior_hook" target_solib_ops method.
 
    For SVR4 executables, this first instruction is either the first
    instruction in the dynamic linker (for dynamically linked
@@ -2165,10 +2043,9 @@ svr4_relocate_main_executable (void)
    shared libraries, maps in the actual user executable, and then
    jumps to "start" in the user executable.
 
-   For both SunOS shared libraries, and SVR4 shared libraries, we
-   can arrange to cooperate with the dynamic linker to discover the
-   names of shared libraries that are dynamically linked, and the
-   base addresses to which they are linked.
+   We can arrange to cooperate with the dynamic linker to discover the
+   names of shared libraries that are dynamically linked, and the base
+   addresses to which they are linked.
 
    This function is responsible for discovering those names and
    addresses, and saving sufficient information about them to allow
@@ -2182,8 +2059,7 @@ svr4_relocate_main_executable (void)
    handling will probably have to wait until the implementation is
    changed to use the "breakpoint handler function" method.
 
-   Also, what if child has exit()ed?  Must exit loop somehow.
- */
+   Also, what if child has exit()ed?  Must exit loop somehow.  */
 
 static void
 svr4_solib_create_inferior_hook (int from_tty)
diff --git a/gdb/solib.c b/gdb/solib.c
index 3296ed4f1ae..f843723250b 100644
--- a/gdb/solib.c
+++ b/gdb/solib.c
@@ -114,17 +114,10 @@ show_solib_search_path (struct ui_file *file, int from_tty,
 #  define DOS_BASED_FILE_SYSTEM 0
 #endif
 
-/*
-
-   GLOBAL FUNCTION
-
-   solib_find -- Find a shared library file.
-
-   SYNOPSIS
-
-   char *solib_find (char *in_pathname, int *fd);
-
-   DESCRIPTION
+/* Returns the full pathname of the shared library file, or NULL if
+   not found.  (The pathname is malloc'ed; it needs to be freed by the
+   caller.)  *FD is set to either -1 or an open file handle for the
+   library.
 
    Global variable GDB_SYSROOT is used as a prefix directory
    to search for shared libraries if they have an absolute path.
@@ -146,12 +139,7 @@ show_solib_search_path (struct ui_file *file, int from_tty,
    *
    * The last check avoids doing this search when targetting remote
    * machines since gdb_sysroot will almost always be set.
-
-   RETURNS
-
-   Full pathname of the shared library file, or NULL if not found.
-   (The pathname is malloc'ed; it needs to be freed by the caller.)
-   *FD is set to either -1 or an open file handle for the library.  */
+*/
 
 char *
 solib_find (char *in_pathname, int *fd)
@@ -452,33 +440,17 @@ solib_bfd_open (char *pathname)
   return abfd;
 }
 
+/* Given a pointer to one of the shared objects in our list of mapped
+   objects, use the recorded name to open a bfd descriptor for the
+   object, build a section table, relocate all the section addresses
+   by the base address at which the shared object was mapped, and then
+   add the sections to the target's section table.
 
-/*
-
-   LOCAL FUNCTION
-
-   solib_map_sections -- open bfd and build sections for shared lib
-
-   SYNOPSIS
-
-   static int solib_map_sections (struct so_list *so)
-
-   DESCRIPTION
-
-   Given a pointer to one of the shared objects in our list
-   of mapped objects, use the recorded name to open a bfd
-   descriptor for the object, build a section table, and then
-   relocate all the section addresses by the base address at
-   which the shared object was mapped.
-
-   FIXMES
-
-   In most (all?) cases the shared object file name recorded in the
-   dynamic linkage tables will be a fully qualified pathname.  For
+   FIXME: In most (all?) cases the shared object file name recorded in
+   the dynamic linkage tables will be a fully qualified pathname.  For
    cases where it isn't, do we really mimic the systems search
    mechanism correctly in the below code (particularly the tilde
-   expansion stuff?).
- */
+   expansion stuff?).  */
 
 static int
 solib_map_sections (struct so_list *so)
@@ -570,17 +542,7 @@ free_so_symbols (struct so_list *so)
   strcpy (so->so_name, so->so_original_name);
 }
 
-/* LOCAL FUNCTION
-
-   free_so --- free a `struct so_list' object
-
-   SYNOPSIS
-
-   void free_so (struct so_list *so)
-
-   DESCRIPTION
-
-   Free the storage associated with the `struct so_list' object SO.
+/* Free the storage associated with the `struct so_list' object SO.
    If we have opened a BFD for SO, close it.
 
    The caller is responsible for removing SO from whatever list it is
@@ -671,13 +633,7 @@ solib_read_symbols (struct so_list *so, int flags)
   return 0;
 }
 
-/* LOCAL FUNCTION
-
-   update_solib_list --- synchronize GDB's shared object list with inferior's
-
-   SYNOPSIS
-
-   void update_solib_list (int from_tty, struct target_ops *TARGET)
+/* Synchronize GDB's shared object list with inferior's.
 
    Extract the list of currently loaded shared objects from the
    inferior, and compare it with the list of shared objects currently
@@ -888,18 +844,7 @@ libpthread_solib_p (struct so_list *so)
   return libpthread_name_p (so->so_name);
 }
 
-/* GLOBAL FUNCTION
-
-   solib_add -- read in symbol info for newly added shared libraries
-
-   SYNOPSIS
-
-   void solib_add (char *pattern, int from_tty, struct target_ops
-   *TARGET, int readsyms)
-
-   DESCRIPTION
-
-   Read in symbolic information for any shared objects whose names
+/* Read in symbolic information for any shared objects whose names
    match PATTERN.  (If we've already read a shared object's symbol
    info, leave it alone.)  If PATTERN is zero, read them all.
 
@@ -982,23 +927,10 @@ solib_add (char *pattern, int from_tty,
   }
 }
 
-
-/*
-
-   LOCAL FUNCTION
-
-   info_sharedlibrary_command -- code for "info sharedlibrary"
-
-   SYNOPSIS
-
-   static void info_sharedlibrary_command ()
-
-   DESCRIPTION
-
-   Walk through the shared library list and print information
-   about each attached library matching PATTERN.  If PATTERN is elided,
-   print them all.
- */
+/* Implement the "info sharedlibrary" command.  Walk through the
+   shared library list and print information about each attached
+   library matching PATTERN.  If PATTERN is elided, print them
+   all.  */
 
 static void
 info_sharedlibrary_command (char *pattern, int from_tty)
@@ -1125,27 +1057,16 @@ solib_contains_address_p (const struct so_list *const solib,
   return 0;
 }
 
-/*
-
-   GLOBAL FUNCTION
-
-   solib_name_from_address -- if an address is in a shared lib, return
-   its name.
-
-   SYNOPSIS
+/* If ADDRESS is in a shared lib in program space PSPACE, return its
+   name.
 
-   char * solib_name_from_address (CORE_ADDR address)
-
-   DESCRIPTION
-
-   Provides a hook for other gdb routines to discover whether or
-   not a particular address is within the mapped address space of
-   a shared library.
+   Provides a hook for other gdb routines to discover whether or not a
+   particular address is within the mapped address space of a shared
+   library.
 
    For example, this routine is called at one point to disable
    breakpoints which are in shared libraries that are not currently
-   mapped in.
- */
+   mapped in.  */
 
 char *
 solib_name_from_address (struct program_space *pspace, CORE_ADDR address)
@@ -1221,20 +1142,10 @@ clear_solib (void)
   ops->clear_solib ();
 }
 
-/* GLOBAL FUNCTION
-
-   solib_create_inferior_hook -- shared library startup support
-
-   SYNOPSIS
-
-   void solib_create_inferior_hook (int from_tty)
-
-   DESCRIPTION
-
-   When gdb starts up the inferior, it nurses it along (through the
-   shell) until it is ready to execute it's first instruction.  At this
-   point, this function gets called via expansion of the macro
-   SOLIB_CREATE_INFERIOR_HOOK.  */
+/* Shared library startup support.  When GDB starts up the inferior,
+   it nurses it along (through the shell) until it is ready to execute
+   its first instruction.  At this point, this function gets
+   called.  */
 
 void
 solib_create_inferior_hook (int from_tty)
@@ -1244,21 +1155,8 @@ solib_create_inferior_hook (int from_tty)
   ops->solib_create_inferior_hook (from_tty);
 }
 
-/* GLOBAL FUNCTION
-
-   in_solib_dynsym_resolve_code -- check to see if an address is in
-                                   dynamic loader's dynamic symbol
-				   resolution code
-
-   SYNOPSIS
-
-   int in_solib_dynsym_resolve_code (CORE_ADDR pc)
-
-   DESCRIPTION
-
-   Determine if PC is in the dynamic linker's symbol resolution
-   code.  Return 1 if so, 0 otherwise.
-*/
+/* Check to see if an address is in the dynamic loader's dynamic
+   symbol resolution code.  Return 1 if so, 0 otherwise.  */
 
 int
 in_solib_dynsym_resolve_code (CORE_ADDR pc)
@@ -1268,19 +1166,7 @@ in_solib_dynsym_resolve_code (CORE_ADDR pc)
   return ops->in_dynsym_resolve_code (pc);
 }
 
-/*
-
-   LOCAL FUNCTION
-
-   sharedlibrary_command -- handle command to explicitly add library
-
-   SYNOPSIS
-
-   static void sharedlibrary_command (char *args, int from_tty)
-
-   DESCRIPTION
-
- */
+/* Implements the "sharedlibrary" command.  */
 
 static void
 sharedlibrary_command (char *args, int from_tty)
@@ -1289,14 +1175,7 @@ sharedlibrary_command (char *args, int from_tty)
   solib_add (args, from_tty, (struct target_ops *) 0, 1);
 }
 
-/* LOCAL FUNCTION
-
-   no_shared_libraries -- handle command to explicitly discard symbols
-   from shared libraries.
-
-   DESCRIPTION
-
-   Implements the command "nosharedlibrary", which discards symbols
+/* Implements the command "nosharedlibrary", which discards symbols
    that have been auto-loaded from shared libraries.  Symbols from
    shared libraries that were added by explicit request of the user
    are not discarded.  Also called from remote.c.  */
diff --git a/gdb/solist.h b/gdb/solist.h
index dad11be46f7..2323343dfe4 100644
--- a/gdb/solist.h
+++ b/gdb/solist.h
@@ -96,14 +96,26 @@ struct target_so_ops
     /* Target dependent code to run after child process fork.  */
     void (*solib_create_inferior_hook) (int from_tty);
 
-    /* Do additional symbol handling, lookup, etc. after symbols
-       for a shared object have been loaded.  */
+    /* Do additional symbol handling, lookup, etc. after symbols for a
+       shared object have been loaded in the usual way.  This is
+       called to do any system specific symbol handling that might be
+       needed.  */
     void (*special_symbol_handling) (void);
 
-    /* Construct a list of the currently loaded shared objects.  */
+    /* Construct a list of the currently loaded shared objects.  This
+       list does not include an entry for the main executable file.
+
+       Note that we only gather information directly available from the
+       inferior --- we don't examine any of the shared library files
+       themselves.  The declaration of `struct so_list' says which fields
+       we provide values for.  */
     struct so_list *(*current_sos) (void);
 
-    /* Find, open, and read the symbols for the main executable.  */
+    /* Find, open, and read the symbols for the main executable.  If
+       FROM_TTYP dereferences to a non-zero integer, allow messages to
+       be printed.  This parameter is a pointer rather than an int
+       because open_symbol_file_object is called via catch_errors and
+       catch_errors requires a pointer argument.  */
     int (*open_symbol_file_object) (void *from_ttyp);
 
     /* Determine if PC lies in the dynamic symbol resolution code of
diff --git a/gdb/somread.c b/gdb/somread.c
index 70831a08e64..70fc3a38c9c 100644
--- a/gdb/somread.c
+++ b/gdb/somread.c
@@ -36,24 +36,12 @@
 
 #include "solib-som.h"
 
-/*
-
-   LOCAL FUNCTION
-
-   som_symtab_read -- read the symbol table of a SOM file
-
-   SYNOPSIS
-
-   void som_symtab_read (bfd *abfd, struct objfile *objfile,
-   struct section_offsets *section_offsets)
-
-   DESCRIPTION
+/* Read the symbol table of a SOM file.
 
    Given an open bfd, a base address to relocate symbols to, and a
    flag that specifies whether or not this bfd is for an executable
    or not (may be shared library for example), add all the global
-   function and data symbols to the minimal symbol table.
- */
+   function and data symbols to the minimal symbol table.  */
 
 static void
 som_symtab_read (bfd *abfd, struct objfile *objfile,