diff --git a/bfd/Makefile.am b/bfd/Makefile.am
index 099229347b5..5c5fdefd3b8 100644
--- a/bfd/Makefile.am
+++ b/bfd/Makefile.am
@@ -904,13 +904,14 @@ stmp-bfd-h: bfd-in3.h
 	rm -f bfd-tmp.h
 	touch stmp-bfd-h
 
-BFD_H_FILES = bfd-in.h opncls.c libbfd.c \
-	bfdio.c bfdwin.c section.c archures.c reloc.c \
-	syms.c bfd.c archive.c corefile.c targets.c format.c \
-	linker.c simple.c compress.c
+BFD_H_FILES = bfd-in.h libbfd.c hash.c section.c syms.c \
+	archive.c archures.c bfd.c bfdio.c bfdwin.c \
+	cache.c compress.c corefile.c format.c linker.c opncls.c \
+	reloc.c simple.c stab-syms.c stabs.c targets.c
 BFD64_H_FILES = archive64.c
-LIBBFD_H_FILES = libbfd-in.h libbfd.c bfd.c bfdio.c bfdwin.c \
-	cache.c reloc.c section.c targets.c archures.c linker.c
+LIBBFD_H_FILES = libbfd-in.h libbfd.c bfd.c bfdio.c \
+	archive.c archures.c bfdwin.c cache.c hash.c linker.c opncls.c \
+	reloc.c section.c stabs.c targets.c
 LIBCOFF_H_FILES = libcoff-in.h coffcode.h
 
 headers: stmp-bin2-h stmp-lbfd-h stmp-lcoff-h
diff --git a/bfd/archive.c b/bfd/archive.c
index 01bfcfc80a1..273a1b3b241 100644
--- a/bfd/archive.c
+++ b/bfd/archive.c
@@ -146,6 +146,37 @@ SUBSECTION
 extern int errno;
 #endif
 
+/*
+EXTERNAL
+.{* A canonical archive symbol.  *}
+.{* This is a type pun with struct symdef/struct ranlib on purpose!  *}
+.typedef struct carsym
+.{
+.  const char *name;
+.  file_ptr file_offset;	{* Look here to find the file.  *}
+.}
+.carsym;
+.
+.{* A count of carsyms (canonical archive symbols).  *}
+. typedef unsigned long symindex;
+.#define BFD_NO_MORE_SYMBOLS ((symindex) ~0)
+.
+
+INTERNAL
+.{* Used in generating armaps (archive tables of contents).  *}
+.struct orl		{* Output ranlib.  *}
+.{
+.  char **name;		{* Symbol name.  *}
+.  union
+.  {
+.    file_ptr pos;
+.    bfd *abfd;
+.  } u;			{* bfd* or file position.  *}
+.  int namidx;		{* Index into string table.  *}
+.};
+.
+*/
+
 /* We keep a cache of archive filepointers to archive elements to
    speed up searching the archive by filepos.  We only add an entry to
    the cache when we actually read one.  We also don't sort the cache;
diff --git a/bfd/archures.c b/bfd/archures.c
index ff1ee0f9de6..6fe8701b412 100644
--- a/bfd/archures.c
+++ b/bfd/archures.c
@@ -947,6 +947,7 @@ DESCRIPTION
 	architecture of the file.
 
 .extern const bfd_arch_info_type bfd_default_arch_struct;
+.
 */
 
 const bfd_arch_info_type bfd_default_arch_struct =
diff --git a/bfd/bfd-in.h b/bfd/bfd-in.h
index 889aa45fcdd..14760396d4a 100644
--- a/bfd/bfd-in.h
+++ b/bfd/bfd-in.h
@@ -75,9 +75,6 @@ extern "C" {
 #define BFD64
 #endif
 
-/* Forward declaration.  */
-typedef struct bfd bfd;
-
 /* Boolean type used in bfd.
    General rule: Functions which are bfd_boolean return TRUE on
    success and FALSE on failure (unless they're a predicate).  */
@@ -130,69 +127,16 @@ typedef uint32_t symvalue;
 typedef @bfd_file_ptr@ file_ptr;
 typedef @bfd_ufile_ptr@ ufile_ptr;
 
-extern void bfd_sprintf_vma (bfd *, char *, bfd_vma);
-extern void bfd_fprintf_vma (bfd *, void *, bfd_vma);
-
-#define bfd_printf_vma(abfd,x) bfd_fprintf_vma (abfd,stdout,x)
-
 typedef uint32_t flagword;	/* 32 bits of flags */
 typedef uint8_t bfd_byte;
-
-/* File formats.  */
-
-typedef enum bfd_format
-{
-  bfd_unknown = 0,	/* File format is unknown.  */
-  bfd_object,		/* Linker/assembler/compiler output.  */
-  bfd_archive,		/* Object archive file.  */
-  bfd_core,		/* Core dump.  */
-  bfd_type_end		/* Marks the end; don't use it!  */
-}
-bfd_format;
-
-/* Symbols and relocation.  */
-
-/* A count of carsyms (canonical archive symbols).  */
-typedef unsigned long symindex;
-
-#define BFD_NO_MORE_SYMBOLS ((symindex) ~0)
 
-/* A canonical archive symbol.  */
-/* This is a type pun with struct ranlib on purpose!  */
-typedef struct carsym
-{
-  const char *name;
-  file_ptr file_offset;	/* Look here to find the file.  */
-}
-carsym;			/* To make these you call a carsymogen.  */
-
-/* Used in generating armaps (archive tables of contents).
-   Perhaps just a forward definition would do?  */
-struct orl		/* Output ranlib.  */
-{
-  char **name;		/* Symbol name.  */
-  union
-  {
-    file_ptr pos;
-    bfd *abfd;
-  } u;			/* bfd* or file position.  */
-  int namidx;		/* Index into string table.  */
-};
-
-/* Linenumber stuff.  */
-typedef struct lineno_cache_entry
-{
-  unsigned int line_number;	/* Linenumber from start of function.  */
-  union
-  {
-    struct bfd_symbol *sym;	/* Function name.  */
-    bfd_vma offset;		/* Offset into section.  */
-  } u;
-}
-alent;
-
-/* Object and core file sections.  */
+/* Forward declarations.  */
+typedef struct bfd bfd;
+struct bfd_link_info;
+struct bfd_link_hash_entry;
 typedef struct bfd_section *sec_ptr;
+typedef struct reloc_cache_entry arelent;
+struct orl;
 
 #define	align_power(addr, align)	\
   (((addr) + ((bfd_vma) 1 << (align)) - 1) & (-((bfd_vma) 1 << (align))))
@@ -205,234 +149,6 @@ typedef struct bfd_section *sec_ptr;
   ((((bfd_vma) (this) + (boundary) - 1) >= (bfd_vma) (this))		  \
    ? (((bfd_vma) (this) + ((boundary) - 1)) & ~ (bfd_vma) ((boundary)-1)) \
    : ~ (bfd_vma) 0)
-
-typedef enum bfd_print_symbol
-{
-  bfd_print_symbol_name,
-  bfd_print_symbol_more,
-  bfd_print_symbol_all
-} bfd_print_symbol_type;
-
-/* Information about a symbol that nm needs.  */
-
-typedef struct _symbol_info
-{
-  symvalue value;
-  char type;
-  const char *name;		/* Symbol name.  */
-  unsigned char stab_type;	/* Stab type.  */
-  char stab_other;		/* Stab other.  */
-  short stab_desc;		/* Stab desc.  */
-  const char *stab_name;	/* String for stab type.  */
-} symbol_info;
-
-/* Get the name of a stabs type code.  */
-
-extern const char *bfd_get_stab_name (int);
-
-/* Hash table routines.  There is no way to free up a hash table.  */
-
-/* An element in the hash table.  Most uses will actually use a larger
-   structure, and an instance of this will be the first field.  */
-
-struct bfd_hash_entry
-{
-  /* Next entry for this hash code.  */
-  struct bfd_hash_entry *next;
-  /* String being hashed.  */
-  const char *string;
-  /* Hash code.  This is the full hash code, not the index into the
-     table.  */
-  unsigned long hash;
-};
-
-/* A hash table.  */
-
-struct bfd_hash_table
-{
-  /* The hash array.  */
-  struct bfd_hash_entry **table;
-  /* A function used to create new elements in the hash table.  The
-     first entry is itself a pointer to an element.  When this
-     function is first invoked, this pointer will be NULL.  However,
-     having the pointer permits a hierarchy of method functions to be
-     built each of which calls the function in the superclass.  Thus
-     each function should be written to allocate a new block of memory
-     only if the argument is NULL.  */
-  struct bfd_hash_entry *(*newfunc)
-    (struct bfd_hash_entry *, struct bfd_hash_table *, const char *);
-  /* An objalloc for this hash table.  This is a struct objalloc *,
-     but we use void * to avoid requiring the inclusion of objalloc.h.  */
-  void *memory;
-  /* The number of slots in the hash table.  */
-  unsigned int size;
-  /* The number of entries in the hash table.  */
-  unsigned int count;
-  /* The size of elements.  */
-  unsigned int entsize;
-  /* If non-zero, don't grow the hash table.  */
-  unsigned int frozen:1;
-};
-
-/* Initialize a hash table.  */
-extern bool bfd_hash_table_init
-  (struct bfd_hash_table *,
-   struct bfd_hash_entry *(*) (struct bfd_hash_entry *,
-			       struct bfd_hash_table *,
-			       const char *),
-   unsigned int);
-
-/* Initialize a hash table specifying a size.  */
-extern bool bfd_hash_table_init_n
-  (struct bfd_hash_table *,
-   struct bfd_hash_entry *(*) (struct bfd_hash_entry *,
-			       struct bfd_hash_table *,
-			       const char *),
-   unsigned int, unsigned int);
-
-/* Free up a hash table.  */
-extern void bfd_hash_table_free
-  (struct bfd_hash_table *);
-
-/* Look up a string in a hash table.  If CREATE is TRUE, a new entry
-   will be created for this string if one does not already exist.  The
-   COPY argument must be TRUE if this routine should copy the string
-   into newly allocated memory when adding an entry.  */
-extern struct bfd_hash_entry *bfd_hash_lookup
-  (struct bfd_hash_table *, const char *, bool create, bool copy);
-
-/* Insert an entry in a hash table.  */
-extern struct bfd_hash_entry *bfd_hash_insert
-  (struct bfd_hash_table *, const char *, unsigned long);
-
-/* Rename an entry in a hash table.  */
-extern void bfd_hash_rename
-  (struct bfd_hash_table *, const char *, struct bfd_hash_entry *);
-
-/* Replace an entry in a hash table.  */
-extern void bfd_hash_replace
-  (struct bfd_hash_table *, struct bfd_hash_entry *old,
-   struct bfd_hash_entry *nw);
-
-/* Base method for creating a hash table entry.  */
-extern struct bfd_hash_entry *bfd_hash_newfunc
-  (struct bfd_hash_entry *, struct bfd_hash_table *, const char *);
-
-/* Grab some space for a hash table entry.  */
-extern void *bfd_hash_allocate
-  (struct bfd_hash_table *, unsigned int);
-
-/* Traverse a hash table in a random order, calling a function on each
-   element.  If the function returns FALSE, the traversal stops.  The
-   INFO argument is passed to the function.  */
-extern void bfd_hash_traverse
-  (struct bfd_hash_table *,
-   bool (*) (struct bfd_hash_entry *, void *),
-   void *info);
-
-/* Allows the default size of a hash table to be configured. New hash
-   tables allocated using bfd_hash_table_init will be created with
-   this size.  */
-extern unsigned int bfd_hash_set_default_size (unsigned int);
-
-/* This structure is used to keep track of stabs in sections
-   information while linking.  */
-
-struct stab_info
-{
-  /* A hash table used to hold stabs strings.  */
-  struct bfd_strtab_hash *strings;
-  /* The header file hash table.  */
-  struct bfd_hash_table includes;
-  /* The first .stabstr section.  */
-  struct bfd_section *stabstr;
-};
-
-#define COFF_SWAP_TABLE (void *) &bfd_coff_std_swap_table
-
-/* User program access to BFD facilities.  */
-
-/* Direct I/O routines, for programs which know more about the object
-   file than BFD does.  Use higher level routines if possible.  */
-
-extern bfd_size_type bfd_bread (void *, bfd_size_type, bfd *);
-extern bfd_size_type bfd_bwrite (const void *, bfd_size_type, bfd *);
-extern int bfd_seek (bfd *, file_ptr, int);
-extern file_ptr bfd_tell (bfd *);
-extern int bfd_flush (bfd *);
-extern int bfd_stat (bfd *, struct stat *);
-
-extern bool bfd_cache_close
-  (bfd *abfd);
-/* NB: This declaration should match the autogenerated one in libbfd.h.  */
-
-extern bool bfd_cache_close_all (void);
-
-extern bool bfd_record_phdr
-  (bfd *, unsigned long, bool, flagword, bool, bfd_vma,
-   bool, bool, unsigned int, struct bfd_section **);
-
-/* Byte swapping routines.  */
-
-uint64_t bfd_getb64 (const void *);
-uint64_t bfd_getl64 (const void *);
-int64_t bfd_getb_signed_64 (const void *);
-int64_t bfd_getl_signed_64 (const void *);
-bfd_vma bfd_getb32 (const void *);
-bfd_vma bfd_getl32 (const void *);
-bfd_signed_vma bfd_getb_signed_32 (const void *);
-bfd_signed_vma bfd_getl_signed_32 (const void *);
-bfd_vma bfd_getb16 (const void *);
-bfd_vma bfd_getl16 (const void *);
-bfd_signed_vma bfd_getb_signed_16 (const void *);
-bfd_signed_vma bfd_getl_signed_16 (const void *);
-void bfd_putb64 (uint64_t, void *);
-void bfd_putl64 (uint64_t, void *);
-void bfd_putb32 (bfd_vma, void *);
-void bfd_putl32 (bfd_vma, void *);
-void bfd_putb24 (bfd_vma, void *);
-void bfd_putl24 (bfd_vma, void *);
-void bfd_putb16 (bfd_vma, void *);
-void bfd_putl16 (bfd_vma, void *);
-
-/* Byte swapping routines which take size and endiannes as arguments.  */
-
-uint64_t bfd_get_bits (const void *, int, bool);
-void bfd_put_bits (uint64_t, void *, int, bool);
-
-
-/* mmap hacks */
-
-struct _bfd_window_internal;
-typedef struct _bfd_window_internal bfd_window_internal;
-
-typedef struct _bfd_window
-{
-  /* What the user asked for.  */
-  void *data;
-  bfd_size_type size;
-  /* The actual window used by BFD.  Small user-requested read-only
-     regions sharing a page may share a single window into the object
-     file.  Read-write versions shouldn't until I've fixed things to
-     keep track of which portions have been claimed by the
-     application; don't want to give the same region back when the
-     application wants two writable copies!  */
-  struct _bfd_window_internal *i;
-}
-bfd_window;
-
-extern void bfd_init_window
-  (bfd_window *);
-extern void bfd_free_window
-  (bfd_window *);
-extern bool bfd_get_file_window
-  (bfd *, file_ptr, bfd_size_type, bfd_window *, bool);
-/* Forward declarations.  */
-struct ecoff_debug_info;
-struct ecoff_debug_swap;
-struct ecoff_extr;
-struct bfd_link_info;
-struct bfd_link_hash_entry;
 
 /* Return TRUE if the start of STR matches PREFIX, FALSE otherwise.  */
 
@@ -441,3 +157,4 @@ startswith (const char *str, const char *prefix)
 {
   return strncmp (str, prefix, strlen (prefix)) == 0;
 }
+
diff --git a/bfd/bfd.c b/bfd/bfd.c
index 650df1c79ed..71debd73733 100644
--- a/bfd/bfd.c
+++ b/bfd/bfd.c
@@ -34,7 +34,16 @@ SECTION
 	contains the major data about the file and pointers
 	to the rest of the data.
 
-CODE_FRAGMENT
+EXTERNAL
+.typedef enum bfd_format
+.  {
+.    bfd_unknown = 0,	{* File format is unknown.  *}
+.    bfd_object,	{* Linker/assembler/compiler output.  *}
+.    bfd_archive,	{* Object archive file.  *}
+.    bfd_core,		{* Core dump.  *}
+.    bfd_type_end	{* Marks the end; don't use it!  *}
+.  }
+.bfd_format;
 .
 .enum bfd_direction
 .  {
@@ -57,6 +66,8 @@ CODE_FRAGMENT
 .    bfd_byte data[1];
 .  };
 .
+
+CODE_FRAGMENT
 .struct bfd
 .{
 .  {* The filename the application opened the BFD with.  *}
@@ -371,6 +382,8 @@ CODE_FRAGMENT
 .  const struct bfd_build_id *build_id;
 .};
 .
+
+EXTERNAL
 .static inline const char *
 .bfd_get_filename (const bfd *abfd)
 .{
@@ -659,7 +672,6 @@ SUBSECTION
 	enumerated type <<bfd_error_type>>.
 
 CODE_FRAGMENT
-.
 .typedef enum bfd_error
 .{
 .  bfd_error_no_error = 0,
@@ -863,7 +875,6 @@ SUBSECTION
 	The BFD error handler acts like vprintf.
 
 CODE_FRAGMENT
-.
 .typedef void (*bfd_error_handler_type) (const char *, va_list);
 .
 */
@@ -1571,7 +1582,6 @@ SUBSECTION
 	_bfd_error_handler and continues.
 
 CODE_FRAGMENT
-.
 .typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg,
 .					  const char *bfd_version,
 .					  const char *bfd_file,
@@ -2289,11 +2299,21 @@ DESCRIPTION
 .#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
 .	BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
 .
-.extern bfd_byte *bfd_get_relocated_section_contents
-.  (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
-.   bool, asymbol **);
-.
+*/
+
+/*
+FUNCTION
+	bfd_get_relocated_section_contents
+
+SYNOPSIS
+	bfd_byte *bfd_get_relocated_section_contents
+	  (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
+	   bool, asymbol **);
 
+DESCRIPTION
+	Read and relocate the indirect link_order section, into DATA
+	(if non-NULL) or to a malloc'd buffer.  Return the buffer, or
+	NULL on errors.
 */
 
 bfd_byte *
@@ -2322,7 +2342,18 @@ bfd_get_relocated_section_contents (bfd *abfd,
   return (*fn) (abfd, link_info, link_order, data, relocatable, symbols);
 }
 
-/* Record information about an ELF program header.  */
+/*
+FUNCTION
+	bfd_record_phdr
+
+SYNOPSIS
+	bool bfd_record_phdr
+	  (bfd *, unsigned long, bool, flagword, bool, bfd_vma,
+	   bool, bool, unsigned int, struct bfd_section **);
+
+DESCRIPTION
+	Record information about an ELF program header.
+*/
 
 bool
 bfd_record_phdr (bfd *abfd,
@@ -2384,8 +2415,23 @@ is32bit (bfd *abfd)
 }
 #endif
 
-/* bfd_sprintf_vma and bfd_fprintf_vma display an address in the
-   target's address size.  */
+/*
+FUNCTION
+	bfd_sprintf_vma
+	bfd_fprintf_vma
+
+SYNOPSIS
+	void bfd_sprintf_vma (bfd *, char *, bfd_vma);
+	void bfd_fprintf_vma (bfd *, void *, bfd_vma);
+
+DESCRIPTION
+	bfd_sprintf_vma and bfd_fprintf_vma display an address in the
+	target's address size.
+
+EXTERNAL
+.#define bfd_printf_vma(abfd,x) bfd_fprintf_vma (abfd, stdout, x)
+.
+*/
 
 void
 bfd_sprintf_vma (bfd *abfd ATTRIBUTE_UNUSED, char *buf, bfd_vma value)
diff --git a/bfd/bfdio.c b/bfd/bfdio.c
index 990d349d428..75a3309c582 100644
--- a/bfd/bfdio.c
+++ b/bfd/bfdio.c
@@ -225,11 +225,21 @@ DESCRIPTION
 .};
 
 .extern const struct bfd_iovec _bfd_memory_iovec;
-
+.
 */
 
 
-/* Return value is amount read.  */
+/*
+FUNCTION
+	bfd_bread
+
+SYNOPSIS
+	bfd_size_type bfd_bread (void *, bfd_size_type, bfd *);
+
+DESCRIPTION
+	Attempt to read SIZE bytes from ABFD's iostream to PTR.
+	Return the amount read.
+*/
 
 bfd_size_type
 bfd_bread (void *ptr, bfd_size_type size, bfd *abfd)
@@ -276,6 +286,18 @@ bfd_bread (void *ptr, bfd_size_type size, bfd *abfd)
   return nread;
 }
 
+/*
+FUNCTION
+	bfd_bwrite
+
+SYNOPSIS
+	bfd_size_type bfd_bwrite (const void *, bfd_size_type, bfd *);
+
+DESCRIPTION
+	Attempt to write SIZE bytes to ABFD's iostream from PTR.
+	Return the amount written.
+*/
+
 bfd_size_type
 bfd_bwrite (const void *ptr, bfd_size_type size, bfd *abfd)
 {
@@ -304,6 +326,17 @@ bfd_bwrite (const void *ptr, bfd_size_type size, bfd *abfd)
   return nwrote;
 }
 
+/*
+FUNCTION
+	bfd_tell
+
+SYNOPSIS
+	file_ptr bfd_tell (bfd *);
+
+DESCRIPTION
+	Return ABFD's iostream file position.
+*/
+
 file_ptr
 bfd_tell (bfd *abfd)
 {
@@ -326,6 +359,17 @@ bfd_tell (bfd *abfd)
   return ptr - offset;
 }
 
+/*
+FUNCTION
+	bfd_flush
+
+SYNOPSIS
+	int bfd_flush (bfd *);
+
+DESCRIPTION
+	Flush ABFD's iostream pending IO.
+*/
+
 int
 bfd_flush (bfd *abfd)
 {
@@ -339,8 +383,18 @@ bfd_flush (bfd *abfd)
   return abfd->iovec->bflush (abfd);
 }
 
-/* Returns 0 for success, negative value for failure (in which case
-   bfd_get_error can retrieve the error code).  */
+/*
+FUNCTION
+	bfd_stat
+
+SYNOPSIS
+	int bfd_stat (bfd *, struct stat *);
+
+DESCRIPTION
+	Call fstat on ABFD's iostream.  Return 0 on success, and a
+	negative value on failure.
+*/
+
 int
 bfd_stat (bfd *abfd, struct stat *statbuf)
 {
@@ -362,8 +416,17 @@ bfd_stat (bfd *abfd, struct stat *statbuf)
   return result;
 }
 
-/* Returns 0 for success, nonzero for failure (in which case bfd_get_error
-   can retrieve the error code).  */
+/*
+FUNCTION
+	bfd_seek
+
+SYNOPSIS
+	int bfd_seek (bfd *, file_ptr, int);
+
+DESCRIPTION
+	Call fseek on ABFD's iostream.  Return 0 on success, and a
+	negative value on failure.
+*/
 
 int
 bfd_seek (bfd *abfd, file_ptr position, int direction)
diff --git a/bfd/bfdwin.c b/bfd/bfdwin.c
index 49b751cbbda..5ecf2f94ee4 100644
--- a/bfd/bfdwin.c
+++ b/bfd/bfdwin.c
@@ -47,15 +47,47 @@ static int debug_windows;
    though.  */
 
 /*
-INTERNAL_DEFINITION
-
-.struct _bfd_window_internal {
+INTERNAL
+.typedef struct _bfd_window_internal
+.{
 .  struct _bfd_window_internal *next;
 .  void *data;
 .  bfd_size_type size;
 .  int refcount : 31;		{* should be enough...  *}
 .  unsigned mapped : 1;		{* 1 = mmap, 0 = malloc *}
-.};
+.}
+.bfd_window_internal;
+.
+
+EXTERNAL
+.struct _bfd_window_internal;
+.
+.typedef struct _bfd_window
+.{
+.  {* What the user asked for.  *}
+.  void *data;
+.  bfd_size_type size;
+.  {* The actual window used by BFD.  Small user-requested read-only
+.     regions sharing a page may share a single window into the object
+.     file.  Read-write versions shouldn't until I've fixed things to
+.     keep track of which portions have been claimed by the
+.     application; don't want to give the same region back when the
+.     application wants two writable copies!  *}
+.  struct _bfd_window_internal *i;
+.}
+.bfd_window;
+.
+*/
+
+/*
+FUNCTION
+	bfd_init_window
+
+SYNOPSIS
+	void bfd_init_window (bfd_window *);
+
+DESCRIPTION
+	Initialise mmap window.
 */
 
 void
@@ -66,6 +98,17 @@ bfd_init_window (bfd_window *windowp)
   windowp->size = 0;
 }
 
+/*
+FUNCTION
+	bfd_free_window
+
+SYNOPSIS
+	void bfd_free_window (bfd_window *);
+
+DESCRIPTION
+	Finalise mmap window struct.
+*/
+
 void
 bfd_free_window (bfd_window *windowp)
 {
@@ -102,7 +145,17 @@ bfd_free_window (bfd_window *windowp)
   free (i);
 }
 
-static int ok_to_map = 1;
+/*
+FUNCTION
+	bfd_get_file_window
+
+SYNOPSIS
+	bool bfd_get_file_window
+	  (bfd *, file_ptr, bfd_size_type, bfd_window *, bool {*writable*});
+
+DESCRIPTION
+	mmap from a bfd's iostream.
+*/
 
 bool
 bfd_get_file_window (bfd *abfd,
@@ -111,6 +164,7 @@ bfd_get_file_window (bfd *abfd,
 		     bfd_window *windowp,
 		     bool writable)
 {
+  static int ok_to_map = 1;
   static size_t pagesize;
   bfd_window_internal *i = windowp->i;
   bfd_size_type size_to_alloc = size;
diff --git a/bfd/cache.c b/bfd/cache.c
index 3b91cce2307..0c6a948b6d6 100644
--- a/bfd/cache.c
+++ b/bfd/cache.c
@@ -509,7 +509,7 @@ bfd_cache_init (bfd *abfd)
 }
 
 /*
-INTERNAL_FUNCTION
+FUNCTION
 	bfd_cache_close
 
 SYNOPSIS
diff --git a/bfd/coffcode.h b/bfd/coffcode.h
index 594f3e0457b..96c53aa2b34 100644
--- a/bfd/coffcode.h
+++ b/bfd/coffcode.h
@@ -290,7 +290,6 @@ DESCRIPTION
 	<<combined_entry_type>>:
 
 CODE_FRAGMENT
-.
 .typedef struct coff_ptr_struct
 .{
 .  {* Remembers the offset from the first symbol in the file for
@@ -333,7 +332,6 @@ CODE_FRAGMENT
 . void *extrap;
 .} combined_entry_type;
 .
-.
 .{* Each canonical asymbol really looks like this: *}
 .
 .typedef struct coff_symbol_struct
@@ -350,7 +348,7 @@ CODE_FRAGMENT
 .  {* Have the line numbers been relocated yet ? *}
 .  bool done_lineno;
 .} coff_symbol_type;
-
+.
 */
 
 #include "libiberty.h"
@@ -1380,8 +1378,7 @@ styp_to_sec_flags (bfd *abfd,
 INTERNAL_DEFINITION
 	bfd_coff_backend_data
 
-CODE_FRAGMENT
-
+INTERNAL
 .{* COFF symbol classifications.  *}
 .
 .enum coff_symbol_classification
@@ -1402,7 +1399,10 @@ CODE_FRAGMENT
 .  (asection *, struct bfd_link_info *, struct internal_reloc *,
 .   struct coff_link_hash_entry *, struct internal_syment *);
 .
+
 Special entry points for gdb to swap in coff symbol table parts:
+
+CODE_FRAGMENT
 .typedef struct
 .{
 .  void (*_bfd_coff_swap_aux_in)
@@ -1540,6 +1540,8 @@ Special entry points for gdb to swap in coff symbol table parts:
 .
 .} bfd_coff_backend_data;
 .
+
+INTERNAL
 .#define coff_backend_info(abfd) \
 .  ((const bfd_coff_backend_data *) (abfd)->xvec->backend_data)
 .
@@ -5460,6 +5462,8 @@ coff_final_link_postscript (bfd * abfd ATTRIBUTE_UNUSED,
 #define coff_SWAP_scnhdr_in coff_swap_scnhdr_in
 #endif
 
+#define COFF_SWAP_TABLE (void *) &bfd_coff_std_swap_table
+
 static const bfd_coff_backend_data bfd_coff_std_swap_table ATTRIBUTE_UNUSED =
 {
   coff_SWAP_aux_in, coff_SWAP_sym_in, coff_SWAP_lineno_in,
diff --git a/bfd/compress.c b/bfd/compress.c
index 844328b27a9..83564fea15f 100644
--- a/bfd/compress.c
+++ b/bfd/compress.c
@@ -32,7 +32,7 @@
 #define MAX_COMPRESSION_HEADER_SIZE 24
 
 /*
-CODE_FRAGMENT
+EXTERNAL
 .{* Types of compressed DWARF debug sections.  *}
 .enum compressed_debug_section_type
 .{
diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index 5257bf42361..c0bd24c6bb8 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -515,11 +515,31 @@ outputdots (void)
       if (at (tos, idx) == '.')
 	{
 	  char c;
+	  int spaces;
 
 	  idx++;
-
+	  spaces = 0;
 	  while ((c = at (tos, idx)) && c != '\n')
 	    {
+	      if (spaces >= 0)
+		{
+		  if (c == ' ')
+		    {
+		      spaces++;
+		      idx++;
+		      continue;
+		    }
+		  else
+		    {
+		      while (spaces >= 8)
+			{
+			  catchar (&out, '\t');
+			  spaces -= 8;
+			}
+		      while (spaces-- > 0)
+			catchar (&out, ' ');
+		    }
+		}
 	      if (c == '{' && at (tos, idx + 1) == '*')
 		{
 		  cattext (&out, "/*");
@@ -795,9 +815,6 @@ icopy_past_newline (void)
   pc++;
 }
 
-/* indent
-   Take the string at the top of the stack, do some prettying.  */
-
 static void
 kill_bogus_lines (void)
 {
@@ -917,6 +934,9 @@ collapse_whitespace (void)
   *tos = out;
 }
 
+/* indent
+   Take the string at the top of the stack, do some prettying.  */
+
 static void
 indent (void)
 {
@@ -930,33 +950,42 @@ indent (void)
       switch (at (tos, idx))
 	{
 	case '\n':
-	  cattext (&out, "\n");
+	  catchar (&out, '\n');
 	  idx++;
 	  if (tab && at (tos, idx))
 	    {
-	      cattext (&out, "    ");
+	      int i;
+	      for (i = 0; i < tab - 1; i += 2)
+		catchar (&out, '\t');
+	      if (i < tab)
+		cattext (&out, "    ");
 	    }
 	  ol = 0;
 	  break;
 	case '(':
-	  tab++;
 	  if (ol == 0)
-	    cattext (&out, "   ");
+	    {
+	      int i;
+	      for (i = 1; i < tab - 1; i += 2)
+		catchar (&out, '\t');
+	      if (i < tab)
+		cattext (&out, "    ");
+	      cattext (&out, "   ");
+	    }
+	  tab++;
 	  idx++;
-	  cattext (&out, "(");
+	  catchar (&out, '(');
 	  ol = 1;
 	  break;
 	case ')':
 	  tab--;
-	  cattext (&out, ")");
+	  catchar (&out, ')');
 	  idx++;
 	  ol = 1;
-
 	  break;
 	default:
 	  catchar (&out, at (tos, idx));
 	  ol = 1;
-
 	  idx++;
 	  break;
 	}
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index f59ff2edd6e..dd0bfe432c1 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -16,6 +16,9 @@
 -  along with this program; if not, write to the Free Software
 -  Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
 
+- chew.c keywords defined here put output into doc/*.texi files
+- from comments in the source.  See also proto.str.
+
 -  True if SYNOPSIS was seen.
 variable synopsis_seen
 
@@ -32,7 +35,6 @@ variable synopsis_seen
 	skip_past_newline	
 	get_stuff_in_command kill_bogus_lines do_fancy_stuff translatecomments 
 	courierize catstr
-
 	;
 
 : INODE 
@@ -73,10 +75,6 @@ variable synopsis_seen
 	catstr 	catstr 	catstr 	catstr 	catstr 
 	;
 
-: FUNCTION
-	func
-	;
-
 : bodytext
 	get_stuff_in_command 
 	bulletize
@@ -109,28 +107,29 @@ variable synopsis_seen
 	bodytext
 	;
 
-
-
-	
 : DESCRIPTION 
 	subhead
 	"@end deftypefn\n" synopsis_seen @ catstrif
 	0 synopsis_seen !
 	;
 
+: FUNCTION
+	func ;
+
 : INTERNAL_FUNCTION
 	func ;
 
+: DEFINITION
+	func ;
 
-: INTERNAL_DEFINITION 
+: INTERNAL_DEFINITION
 	func ;
 
+: EXTERNAL
+	COMMENT ;
 
 : INTERNAL
-	func ;
-
-: TYPEDEF
-	FUNCTION ;
+	COMMENT ;
 
 : SENUM
 	skip_past_newline
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
index 3b776736067..90ee01106db 100644
--- a/bfd/doc/proto.str
+++ b/bfd/doc/proto.str
@@ -16,13 +16,35 @@
 -  along with this program; if not, write to the Free Software
 -  Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
 
+- chew.c keywords defined here put output into bfd-in2.h and libbfd.h or
+- libcoff.h, from comments in the source.  See also doc.str.
+- Output lines generally come from comment lines starting with a dot,
+- or from keywords like SYNOPSIS.  Output switches to bfd-in2.h at the
+- end of each comment.  Use INTERNAL* to output to libbfd.h.
+-
+- EXTERNAL: output to bfd-in2.h, nothing to docs
+- INTERNAL: output to libbfd.h, nothing to docs
+- CODE_FRAGMENT: output to header and docs
+- FUNCTION: output to bfd-in2.h and docs
+- INTERNAL_FUNCTION: output to libbfd.h and docs
+- DEFINITION: alias for FUNCTION, but generally doesn't have SYNOPSIS,
+-	used for structs and other random code
+- INTERNAL_DEFINITION: as above, but output to libbfd.h and docs
+- ENUM* outputs to bfd-in2.h, libbfd.h and docs.
+
 : SYNOPSIS
 	skip_past_newline
 	get_stuff_in_command	
+	translatecomments
+	strip_trailing_newlines
+	remchar
+	" ATTRIBUTE_HIDDEN" internalmode @ catstrif
+	";\n\n" catstr
 	indent
 	maybecatstr
 ;
 
+- Ignore stuff that is for the docs.  Output lines starting with dots.
 : ignore
 	skip_past_newline 
 	get_stuff_in_command
@@ -33,10 +55,12 @@
 : CODE_FRAGMENT
 	ignore ;
 
-: external
+- Output goes to bfd-in2.h
+: EXTERNAL
 	0 internalmode ! ignore ;
 
-: internal 
+- Output goes to libbfd.h/libcoff.h
+: INTERNAL 
 	1 internalmode ! ignore ;
 
 - input stack { a b } output b if internal, a if external
@@ -137,14 +161,13 @@
 	swap
 	catstr catstr
 	;
-: ENDDD external ;
 : SECTION ignore ;
 : SUBSECTION ignore ;
 : SUBSUBSECTION ignore ;
-: INTERNAL_DEFINITION internal ;
-: DESCRIPTION ignore ;
-: FUNCTION external ;
-: TYPEDEF external ;
-: INTERNAL_FUNCTION internal ;
-: INTERNAL internal ;
 : INODE ignore ;
+: DESCRIPTION ignore ;
+: ENDDD EXTERNAL ;
+: FUNCTION EXTERNAL ;
+: INTERNAL_FUNCTION INTERNAL ;
+: DEFINITION EXTERNAL ;
+: INTERNAL_DEFINITION INTERNAL ;
diff --git a/bfd/elfxx-mips.h b/bfd/elfxx-mips.h
index f15dceac48e..2c790ed5ed6 100644
--- a/bfd/elfxx-mips.h
+++ b/bfd/elfxx-mips.h
@@ -33,6 +33,8 @@ enum reloc_check
 #define MIPS_DEFAULT_R6 0
 #endif
 
+struct ecoff_debug_info;
+
 extern bool _bfd_mips_elf_mkobject
   (bfd *);
 extern bool _bfd_mips_elf_close_and_cleanup
diff --git a/bfd/hash.c b/bfd/hash.c
index add7d10ecb3..483593eb6f0 100644
--- a/bfd/hash.c
+++ b/bfd/hash.c
@@ -295,6 +295,50 @@ SUBSUBSECTION
 	linker hash table, uses macros for the lookup and traversal
 	routines.  These are <<aout_link_hash_lookup>> and
 	<<aout_link_hash_traverse>> in aoutx.h.
+
+EXTERNAL
+.{* An element in the hash table.  Most uses will actually use a larger
+.   structure, and an instance of this will be the first field.  *}
+.
+.struct bfd_hash_entry
+.{
+.  {* Next entry for this hash code.  *}
+.  struct bfd_hash_entry *next;
+.  {* String being hashed.  *}
+.  const char *string;
+.  {* Hash code.  This is the full hash code, not the index into the
+.     table.  *}
+.  unsigned long hash;
+.};
+.
+.{* A hash table.  *}
+.
+.struct bfd_hash_table
+.{
+.  {* The hash array.  *}
+.  struct bfd_hash_entry **table;
+.  {* A function used to create new elements in the hash table.  The
+.     first entry is itself a pointer to an element.  When this
+.     function is first invoked, this pointer will be NULL.  However,
+.     having the pointer permits a hierarchy of method functions to be
+.     built each of which calls the function in the superclass.  Thus
+.     each function should be written to allocate a new block of memory
+.     only if the argument is NULL.  *}
+.  struct bfd_hash_entry *(*newfunc)
+.    (struct bfd_hash_entry *, struct bfd_hash_table *, const char *);
+.  {* An objalloc for this hash table.  This is a struct objalloc *,
+.     but we use void * to avoid requiring the inclusion of objalloc.h.  *}
+.  void *memory;
+.  {* The number of slots in the hash table.  *}
+.  unsigned int size;
+.  {* The number of entries in the hash table.  *}
+.  unsigned int count;
+.  {* The size of elements.  *}
+.  unsigned int entsize;
+.  {* If non-zero, don't grow the hash table.  *}
+.  unsigned int frozen:1;
+.};
+.
 */
 
 /* The default number of entries to use when creating a hash table.  */
@@ -361,7 +405,20 @@ higher_prime_number (uint32_t n)
 
 static unsigned int bfd_default_hash_table_size = DEFAULT_SIZE;
 
-/* Create a new hash table, given a number of entries.  */
+/*
+FUNCTION
+	bfd_hash_table_init_n
+
+SYNOPSIS
+	bool bfd_hash_table_init_n
+	  (struct bfd_hash_table *,
+	   struct bfd_hash_entry *(* {*newfunc*})
+	     (struct bfd_hash_entry *, struct bfd_hash_table *, const char *),
+	   unsigned int {*entsize*}, unsigned int {*size*});
+
+DESCRIPTION
+	Create a new hash table, given a number of entries.
+*/
 
 bool
 bfd_hash_table_init_n (struct bfd_hash_table *table,
@@ -404,7 +461,20 @@ bfd_hash_table_init_n (struct bfd_hash_table *table,
   return true;
 }
 
-/* Create a new hash table with the default number of entries.  */
+/*
+FUNCTION
+	bfd_hash_table_init
+
+SYNOPSIS
+	bool bfd_hash_table_init
+	  (struct bfd_hash_table *,
+	   struct bfd_hash_entry *(* {*newfunc*})
+	     (struct bfd_hash_entry *, struct bfd_hash_table *, const char *),
+	   unsigned int {*entsize*});
+
+DESCRIPTION
+	Create a new hash table with the default number of entries.
+*/
 
 bool
 bfd_hash_table_init (struct bfd_hash_table *table,
@@ -417,7 +487,16 @@ bfd_hash_table_init (struct bfd_hash_table *table,
 				bfd_default_hash_table_size);
 }
 
-/* Free a hash table.  */
+/*
+FUNCTION
+	bfd_hash_table_free
+
+SYNOPSIS
+	void bfd_hash_table_free (struct bfd_hash_table *);
+
+DESCRIPTION
+	Free a hash table.
+*/
 
 void
 bfd_hash_table_free (struct bfd_hash_table *table)
@@ -451,7 +530,18 @@ bfd_hash_hash (const char *string, unsigned int *lenp)
   return hash;
 }
 
-/* Look up a string in a hash table.  */
+/*
+FUNCTION
+	bfd_hash_lookup
+
+SYNOPSIS
+	struct bfd_hash_entry *bfd_hash_lookup
+	  (struct bfd_hash_table *, const char *,
+	   bool {*create*}, bool {*copy*});
+
+DESCRIPTION
+	Look up a string in a hash table.
+*/
 
 struct bfd_hash_entry *
 bfd_hash_lookup (struct bfd_hash_table *table,
@@ -496,7 +586,19 @@ bfd_hash_lookup (struct bfd_hash_table *table,
   return bfd_hash_insert (table, string, hash);
 }
 
-/* Insert an entry in a hash table.  */
+/*
+FUNCTION
+	bfd_hash_insert
+
+SYNOPSIS
+	struct bfd_hash_entry *bfd_hash_insert
+	  (struct bfd_hash_table *,
+	   const char *,
+	   unsigned long {*hash*});
+
+DESCRIPTION
+	Insert an entry in a hash table.
+*/
 
 struct bfd_hash_entry *
 bfd_hash_insert (struct bfd_hash_table *table,
@@ -561,7 +663,18 @@ bfd_hash_insert (struct bfd_hash_table *table,
   return hashp;
 }
 
-/* Rename an entry in a hash table.  */
+/*
+FUNCTION
+	bfd_hash_rename
+
+SYNOPSIS
+	void bfd_hash_rename (struct bfd_hash_table *,
+			      const char *,
+			      struct bfd_hash_entry *);
+
+DESCRIPTION
+	Rename an entry in a hash table.
+*/
 
 void
 bfd_hash_rename (struct bfd_hash_table *table,
@@ -586,7 +699,18 @@ bfd_hash_rename (struct bfd_hash_table *table,
   table->table[_index] = ent;
 }
 
-/* Replace an entry in a hash table.  */
+/*
+FUNCTION
+	bfd_hash_replace
+
+SYNOPSIS
+	void bfd_hash_replace (struct bfd_hash_table *,
+			       struct bfd_hash_entry * {*old*},
+			       struct bfd_hash_entry * {*new*});
+
+DESCRIPTION
+	Replace an entry in a hash table.
+*/
 
 void
 bfd_hash_replace (struct bfd_hash_table *table,
@@ -611,7 +735,17 @@ bfd_hash_replace (struct bfd_hash_table *table,
   abort ();
 }
 
-/* Allocate space in a hash table.  */
+/*
+FUNCTION
+	bfd_hash_allocate
+
+SYNOPSIS
+	void *bfd_hash_allocate (struct bfd_hash_table *,
+				 unsigned int {*size*});
+
+DESCRIPTION
+	Allocate space in a hash table.
+*/
 
 void *
 bfd_hash_allocate (struct bfd_hash_table *table,
@@ -625,7 +759,19 @@ bfd_hash_allocate (struct bfd_hash_table *table,
   return ret;
 }
 
-/* Base method for creating a new hash table entry.  */
+/*
+FUNCTION
+	bfd_hash_newfunc
+
+SYNOPSIS
+	struct bfd_hash_entry *bfd_hash_newfunc
+	  (struct bfd_hash_entry *,
+	   struct bfd_hash_table *,
+	   const char *);
+
+DESCRIPTION
+	Base method for creating a new hash table entry.
+*/
 
 struct bfd_hash_entry *
 bfd_hash_newfunc (struct bfd_hash_entry *entry,
@@ -638,12 +784,24 @@ bfd_hash_newfunc (struct bfd_hash_entry *entry,
   return entry;
 }
 
-/* Traverse a hash table.  */
+/*
+FUNCTION
+	bfd_hash_traverse
+
+SYNOPSIS
+	void bfd_hash_traverse
+	  (struct bfd_hash_table *,
+	   bool (*) (struct bfd_hash_entry *, void *),
+	   void *);
+
+DESCRIPTION
+	Traverse a hash table.
+*/
 
 void
 bfd_hash_traverse (struct bfd_hash_table *table,
 		   bool (*func) (struct bfd_hash_entry *, void *),
-		   void * info)
+		   void *info)
 {
   unsigned int i;
 
@@ -660,6 +818,17 @@ bfd_hash_traverse (struct bfd_hash_table *table,
   table->frozen = 0;
 }
 
+/*
+FUNCTION
+	bfd_hash_set_default_size
+
+SYNOPSIS
+	unsigned int bfd_hash_set_default_size (unsigned int);
+
+DESCRIPTION
+	Set hash table default size.
+*/
+
 unsigned int
 bfd_hash_set_default_size (unsigned int hash_size)
 {
@@ -755,7 +924,16 @@ strtab_hash_newfunc (struct bfd_hash_entry *entry,
   ((struct strtab_hash_entry *) \
    bfd_hash_lookup (&(t)->table, (string), (create), (copy)))
 
-/* Create a new strtab.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_stringtab_init
+
+SYNOPSIS
+	struct bfd_strtab_hash *_bfd_stringtab_init (void);
+
+DESCRIPTION
+	Create a new strtab.
+*/
 
 struct bfd_strtab_hash *
 _bfd_stringtab_init (void)
@@ -782,9 +960,19 @@ _bfd_stringtab_init (void)
   return table;
 }
 
-/* Create a new strtab in which the strings are output in the format
-   used in the XCOFF .debug section: a two byte length precedes each
-   string.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_xcoff_stringtab_init
+
+SYNOPSIS
+	struct bfd_strtab_hash *_bfd_xcoff_stringtab_init
+	  (bool {*isxcoff64*});
+
+DESCRIPTION
+	Create a new strtab in which the strings are output in the format
+	used in the XCOFF .debug section: a two byte length precedes each
+	string.
+*/
 
 struct bfd_strtab_hash *
 _bfd_xcoff_stringtab_init (bool isxcoff64)
@@ -797,7 +985,16 @@ _bfd_xcoff_stringtab_init (bool isxcoff64)
   return ret;
 }
 
-/* Free a strtab.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_stringtab_free
+
+SYNOPSIS
+	void _bfd_stringtab_free (struct bfd_strtab_hash *);
+
+DESCRIPTION
+	Free a strtab.
+*/
 
 void
 _bfd_stringtab_free (struct bfd_strtab_hash *table)
@@ -806,10 +1003,21 @@ _bfd_stringtab_free (struct bfd_strtab_hash *table)
   free (table);
 }
 
-/* Get the index of a string in a strtab, adding it if it is not
-   already present.  If HASH is FALSE, we don't really use the hash
-   table, and we don't eliminate duplicate strings.  If COPY is true
-   then store a copy of STR if creating a new entry.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_stringtab_add
+
+SYNOPSIS
+	bfd_size_type _bfd_stringtab_add
+	  (struct bfd_strtab_hash *, const char *,
+	   bool {*hash*}, bool {*copy*});
+
+DESCRIPTION
+	Get the index of a string in a strtab, adding it if it is not
+	already present.  If HASH is FALSE, we don't really use the hash
+	table, and we don't eliminate duplicate strings.  If COPY is true
+	then store a copy of STR if creating a new entry.
+*/
 
 bfd_size_type
 _bfd_stringtab_add (struct bfd_strtab_hash *tab,
@@ -864,7 +1072,16 @@ _bfd_stringtab_add (struct bfd_strtab_hash *tab,
   return entry->index;
 }
 
-/* Get the number of bytes in a strtab.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_stringtab_size
+
+SYNOPSIS
+	bfd_size_type _bfd_stringtab_size (struct bfd_strtab_hash *);
+
+DESCRIPTION
+	Get the number of bytes in a strtab.
+*/
 
 bfd_size_type
 _bfd_stringtab_size (struct bfd_strtab_hash *tab)
@@ -872,8 +1089,17 @@ _bfd_stringtab_size (struct bfd_strtab_hash *tab)
   return tab->size;
 }
 
-/* Write out a strtab.  ABFD must already be at the right location in
-   the file.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_stringtab_emit
+
+SYNOPSIS
+	bool _bfd_stringtab_emit (bfd *, struct bfd_strtab_hash *);
+
+DESCRIPTION
+	Write out a strtab.  ABFD must already be at the right location in
+	the file.
+*/
 
 bool
 _bfd_stringtab_emit (bfd *abfd, struct bfd_strtab_hash *tab)
diff --git a/bfd/libbfd-in.h b/bfd/libbfd-in.h
index ca15b8b0a23..b3f5190e370 100644
--- a/bfd/libbfd-in.h
+++ b/bfd/libbfd-in.h
@@ -170,10 +170,6 @@ extern bfd *_bfd_get_elt_at_filepos
   (bfd *, file_ptr, struct bfd_link_info *) ATTRIBUTE_HIDDEN;
 extern bfd *_bfd_generic_get_elt_at_index
   (bfd *, symindex) ATTRIBUTE_HIDDEN;
-extern bfd * _bfd_new_bfd
-  (void) ATTRIBUTE_HIDDEN;
-extern bool _bfd_free_cached_info
-  (bfd *) ATTRIBUTE_HIDDEN;
 
 extern bool _bfd_bool_bfd_false
   (bfd *) ATTRIBUTE_HIDDEN;
@@ -214,8 +210,6 @@ extern void _bfd_void_bfd_link
 extern void _bfd_void_bfd_asection
   (bfd *, asection *) ATTRIBUTE_HIDDEN;
 
-extern bfd *_bfd_new_bfd_contained_in
-  (bfd *) ATTRIBUTE_HIDDEN;
 extern bfd_cleanup _bfd_dummy_target
   (bfd *) ATTRIBUTE_HIDDEN;
 #define _bfd_no_cleanup _bfd_void_bfd
@@ -709,34 +703,6 @@ extern bfd_reloc_status_type _bfd_relocate_contents
 extern bfd_reloc_status_type _bfd_clear_contents
   (reloc_howto_type *, bfd *, asection *, bfd_byte *, bfd_vma) ATTRIBUTE_HIDDEN;
 
-/* Link stabs in sections in the first pass.  */
-
-extern bool _bfd_link_section_stabs
-  (bfd *, struct stab_info *, asection *, asection *, void **,
-   bfd_size_type *) ATTRIBUTE_HIDDEN;
-
-/* Eliminate stabs for discarded functions and symbols.  */
-extern bool _bfd_discard_section_stabs
-  (bfd *, asection *, void *, bool (*) (bfd_vma, void *), void *)
-  ATTRIBUTE_HIDDEN;
-
-/* Write out the .stab section when linking stabs in sections.  */
-
-extern bool _bfd_write_section_stabs
-  (bfd *, struct stab_info *, asection *, void **, bfd_byte *)
-  ATTRIBUTE_HIDDEN;
-
-/* Write out the .stabstr string table when linking stabs in sections.  */
-
-extern bool _bfd_write_stab_strings
-  (bfd *, struct stab_info *) ATTRIBUTE_HIDDEN;
-
-/* Find an offset within a .stab section when linking stabs in
-   sections.  */
-
-extern bfd_vma _bfd_stab_section_offset
-  (asection *, void *, bfd_vma) ATTRIBUTE_HIDDEN;
-
 /* Register a SEC_MERGE section as a candidate for merging.  */
 
 extern bool _bfd_add_merge_section
@@ -762,31 +728,6 @@ extern bfd_vma _bfd_merged_section_offset
 
 extern void _bfd_merge_sections_free (void *) ATTRIBUTE_HIDDEN;
 
-/* Create a string table.  */
-extern struct bfd_strtab_hash *_bfd_stringtab_init
-  (void) ATTRIBUTE_HIDDEN;
-
-/* Create an XCOFF .debug section style string table.  */
-extern struct bfd_strtab_hash *_bfd_xcoff_stringtab_init
-  (bool isxcoff64) ATTRIBUTE_HIDDEN;
-
-/* Free a string table.  */
-extern void _bfd_stringtab_free
-  (struct bfd_strtab_hash *) ATTRIBUTE_HIDDEN;
-
-/* Get the size of a string table.  */
-extern bfd_size_type _bfd_stringtab_size
-  (struct bfd_strtab_hash *) ATTRIBUTE_HIDDEN;
-
-/* Add a string to a string table.  */
-extern bfd_size_type _bfd_stringtab_add
-  (struct bfd_strtab_hash *, const char *, bool hash, bool copy)
-  ATTRIBUTE_HIDDEN;
-
-/* Write out a string table.  */
-extern bool _bfd_stringtab_emit
-  (bfd *, struct bfd_strtab_hash *) ATTRIBUTE_HIDDEN;
-
 /* Macros to tell if bfds are read or write enabled.
 
    Note that bfds open for read may be scribbled into if the fd passed
@@ -841,9 +782,10 @@ extern const bfd_target *const *const bfd_associated_vector ATTRIBUTE_HIDDEN;
 /* Functions shared by the ECOFF and MIPS ELF backends, which have no
    other common header files.  */
 
-#if defined(__STDC__) || defined(ALMOST_STDC)
+struct ecoff_debug_info;
+struct ecoff_debug_swap;
+struct ecoff_extr;
 struct ecoff_find_line;
-#endif
 
 extern bool _bfd_ecoff_locate_line
   (bfd *, asection *, bfd_vma, struct ecoff_debug_info * const,
diff --git a/bfd/libbfd.c b/bfd/libbfd.c
index 66ef32469fb..7c750472ade 100644
--- a/bfd/libbfd.c
+++ b/bfd/libbfd.c
@@ -264,7 +264,7 @@ INTERNAL_FUNCTION
 	bfd_malloc
 
 SYNOPSIS
-	extern void * bfd_malloc (bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+	void *bfd_malloc (bfd_size_type {*size*});
 
 DESCRIPTION
 	Returns a pointer to an allocated block of memory that is at least
@@ -299,7 +299,7 @@ INTERNAL_FUNCTION
 	bfd_realloc
 
 SYNOPSIS
-	extern void * bfd_realloc (void * MEM, bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+	void *bfd_realloc (void *{*mem*}, bfd_size_type {*size*});
 
 DESCRIPTION
 	Returns a pointer to an allocated block of memory that is at least
@@ -349,7 +349,7 @@ INTERNAL_FUNCTION
 	bfd_realloc_or_free
 
 SYNOPSIS
-	extern void * bfd_realloc_or_free (void * MEM, bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+	void *bfd_realloc_or_free (void *{*mem*}, bfd_size_type {*size*});
 
 DESCRIPTION
 	Returns a pointer to an allocated block of memory that is at least
@@ -394,7 +394,7 @@ INTERNAL_FUNCTION
 	bfd_zmalloc
 
 SYNOPSIS
-	extern void * bfd_zmalloc (bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+	void *bfd_zmalloc (bfd_size_type {*size*});
 
 DESCRIPTION
 	Returns a pointer to an allocated block of memory that is at least
@@ -701,6 +701,35 @@ DESCRIPTION
 #define COERCE64(x) \
   (((uint64_t) (x) ^ ((uint64_t) 1 << 63)) - ((uint64_t) 1 << 63))
 
+/*
+FUNCTION
+	Byte swapping routines.
+
+SYNOPSIS
+	uint64_t bfd_getb64 (const void *);
+	uint64_t bfd_getl64 (const void *);
+	int64_t bfd_getb_signed_64 (const void *);
+	int64_t bfd_getl_signed_64 (const void *);
+	bfd_vma bfd_getb32 (const void *);
+	bfd_vma bfd_getl32 (const void *);
+	bfd_signed_vma bfd_getb_signed_32 (const void *);
+	bfd_signed_vma bfd_getl_signed_32 (const void *);
+	bfd_vma bfd_getb16 (const void *);
+	bfd_vma bfd_getl16 (const void *);
+	bfd_signed_vma bfd_getb_signed_16 (const void *);
+	bfd_signed_vma bfd_getl_signed_16 (const void *);
+	void bfd_putb64 (uint64_t, void *);
+	void bfd_putl64 (uint64_t, void *);
+	void bfd_putb32 (bfd_vma, void *);
+	void bfd_putl32 (bfd_vma, void *);
+	void bfd_putb24 (bfd_vma, void *);
+	void bfd_putl24 (bfd_vma, void *);
+	void bfd_putb16 (bfd_vma, void *);
+	void bfd_putl16 (bfd_vma, void *);
+	uint64_t bfd_get_bits (const void *, int, bool);
+	void bfd_put_bits (uint64_t, void *, int, bool);
+*/
+
 bfd_vma
 bfd_getb16 (const void *p)
 {
diff --git a/bfd/linker.c b/bfd/linker.c
index e57c9ee0486..0f4f9a1776c 100644
--- a/bfd/linker.c
+++ b/bfd/linker.c
@@ -3399,6 +3399,7 @@ DESCRIPTION
 .#define bfd_merge_private_bfd_data(ibfd, info) \
 .	BFD_SEND ((info)->output_bfd, _bfd_merge_private_bfd_data, \
 .		  (ibfd, info))
+.
 */
 
 /*
diff --git a/bfd/opncls.c b/bfd/opncls.c
index b7b9d8f2d0b..f0064954bf3 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -51,16 +51,26 @@ static unsigned int bfd_id_counter = 0;
 static unsigned int bfd_reserved_id_counter = 0;
 
 /*
-CODE_FRAGMENT
+EXTERNAL
 .{* Set to N to open the next N BFDs using an alternate id space.  *}
 .extern unsigned int bfd_use_reserved_id;
+.
 */
 unsigned int bfd_use_reserved_id = 0;
 
 /* fdopen is a loser -- we should use stdio exclusively.  Unfortunately
    if we do that we can't use fcntl.  */
 
-/* Return a new BFD.  All BFD's are allocated through this routine.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_new_bfd
+
+SYNOPSIS
+	bfd *_bfd_new_bfd (void);
+
+DESCRIPTION
+	Return a new BFD.  All BFD's are allocated through this routine.
+*/
 
 bfd *
 _bfd_new_bfd (void)
@@ -104,7 +114,16 @@ _bfd_new_bfd (void)
 
 static const struct bfd_iovec opncls_iovec;
 
-/* Allocate a new BFD as a member of archive OBFD.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_new_bfd_contained_in
+
+SYNOPSIS
+	bfd *_bfd_new_bfd_contained_in (bfd *);
+
+DESCRIPTION
+	Allocate a new BFD as a member of archive OBFD.
+*/
 
 bfd *
 _bfd_new_bfd_contained_in (bfd *obfd)
@@ -149,7 +168,16 @@ _bfd_delete_bfd (bfd *abfd)
   free (abfd);
 }
 
-/* Free objalloc memory.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_free_cached_info
+
+SYNOPSIS
+	bool _bfd_free_cached_info (bfd *);
+
+DESCRIPTION
+	Free objalloc memory.
+*/
 
 bool
 _bfd_free_cached_info (bfd *abfd)
diff --git a/bfd/reloc.c b/bfd/reloc.c
index 16540632613..aab5d49bdb3 100644
--- a/bfd/reloc.c
+++ b/bfd/reloc.c
@@ -62,8 +62,7 @@ SUBSECTION
 
 	This is the structure of a relocation entry:
 
-CODE_FRAGMENT
-.
+EXTERNAL
 .typedef enum bfd_reloc_status
 .{
 .  {* No errors detected.  Note - the value 2 is used so that it
@@ -97,7 +96,9 @@ CODE_FRAGMENT
 .
 .typedef const struct reloc_howto_struct reloc_howto_type;
 .
-.typedef struct reloc_cache_entry
+
+CODE_FRAGMENT
+.struct reloc_cache_entry
 .{
 .  {* A pointer into the canonical table of pointers.  *}
 .  struct bfd_symbol **sym_ptr_ptr;
@@ -111,8 +112,7 @@ CODE_FRAGMENT
 .  {* Pointer to how to perform the required relocation.  *}
 .  reloc_howto_type *howto;
 .
-.}
-.arelent;
+.};
 .
 */
 
@@ -251,7 +251,6 @@ SUBSUBSECTION
 	performing a relocation.
 
 CODE_FRAGMENT
-.
 .enum complain_overflow
 .{
 .  {* Do not complain on overflow.  *}
@@ -270,7 +269,7 @@ CODE_FRAGMENT
 .     unsigned number.  *}
 .  complain_overflow_unsigned
 .};
-
+.
 */
 
 /*
@@ -402,11 +401,10 @@ DESCRIPTION
 */
 
 /*
-TYPEDEF
+DEFINITION
 	arelent_chain
 
 DESCRIPTION
-
 	How relocs are tied together in an <<asection>>:
 
 .typedef struct relent_chain
@@ -1372,8 +1370,8 @@ SUBSECTION
 */
 
 /*
-TYPEDEF
-	bfd_reloc_code_type
+DEFINITION
+	bfd_reloc_code_real_type
 
 DESCRIPTION
 	The insides of a reloc code.  The idea is that, eventually, there
@@ -8134,9 +8132,10 @@ ENUMDOC
 
 ENDSENUM
   BFD_RELOC_UNUSED
+
 CODE_FRAGMENT
-.
 .typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
+.
 */
 
 /*
@@ -8154,7 +8153,6 @@ DESCRIPTION
 	Return a pointer to a howto structure which, when
 	invoked, will perform the relocation @var{code} on data from the
 	architecture noted.
-
 */
 
 reloc_howto_type *
@@ -8182,7 +8180,6 @@ SYNOPSIS
 
 DESCRIPTION
 	Provides a default relocation lookup routine for any architecture.
-
 */
 
 reloc_howto_type *
@@ -8329,7 +8326,6 @@ SYNOPSIS
 DESCRIPTION
 	Provides default handling of relocation effort for back ends
 	which can't be bothered to do it efficiently.
-
 */
 
 bfd_byte *
diff --git a/bfd/section.c b/bfd/section.c
index 1e7e8ac7522..73770294e56 100644
--- a/bfd/section.c
+++ b/bfd/section.c
@@ -137,14 +137,27 @@ SUBSECTION
 /*
 DOCDD
 INODE
-typedef asection, section prototypes, Section Output, Sections
+	typedef asection, section prototypes, Section Output, Sections
 SUBSECTION
 	typedef asection
 
 	Here is the section structure:
 
-CODE_FRAGMENT
+EXTERNAL
+.{* Linenumber stuff.  *}
+.typedef struct lineno_cache_entry
+.{
+.  unsigned int line_number;	{* Linenumber from start of function.  *}
+.  union
+.  {
+.    struct bfd_symbol *sym;	{* Function name.  *}
+.    bfd_vma offset;		{* Offset into section.  *}
+.  } u;
+.}
+.alent;
 .
+
+CODE_FRAGMENT
 .typedef struct bfd_section
 .{
 .  {* The name of the section; the name isn't a copy, the pointer is
@@ -493,7 +506,7 @@ CODE_FRAGMENT
 .
 .  {* If the SEC_IN_MEMORY flag is set, this points to the actual
 .     contents.  *}
-.  unsigned char *contents;
+.  bfd_byte *contents;
 .
 .  {* Attached line number information.  *}
 .  alent *lineno;
@@ -549,6 +562,8 @@ CODE_FRAGMENT
 .
 .} asection;
 .
+
+EXTERNAL
 .static inline const char *
 .bfd_section_name (const asection *sec)
 .{
diff --git a/bfd/stab-syms.c b/bfd/stab-syms.c
index 3b2e42d0760..eeb8c618185 100644
--- a/bfd/stab-syms.c
+++ b/bfd/stab-syms.c
@@ -44,6 +44,17 @@
   __define_name (N_INDR, "INDR") \
   __define_name (N_WARNING, "WARNING")
 
+/*
+FUNCTION
+	bfd_get_stab_name
+
+SYNOPSIS
+	const char *bfd_get_stab_name (int);
+
+DESCRIPTION
+	Get the name of a stabs type code.
+*/
+
 const char *
 bfd_get_stab_name (int code)
 {
diff --git a/bfd/stabs.c b/bfd/stabs.c
index 1cce2ae4f3f..455bf8b345a 100644
--- a/bfd/stabs.c
+++ b/bfd/stabs.c
@@ -112,7 +112,23 @@ struct stab_section_info
   bfd_size_type stridxs[1];
 };
 
-
+/*
+EXTERNAL
+.{* This structure is used to keep track of stabs in sections
+.   information while linking.  *}
+.
+.struct stab_info
+.{
+.  {* A hash table used to hold stabs strings.  *}
+.  struct bfd_strtab_hash *strings;
+.  {* The header file hash table.  *}
+.  struct bfd_hash_table includes;
+.  {* The first .stabstr section.  *}
+.  struct bfd_section *stabstr;
+.};
+.
+*/
+
 /* The function to create a new entry in the header file hash table.  */
 
 static struct bfd_hash_entry *
@@ -140,9 +156,20 @@ stab_link_includes_newfunc (struct bfd_hash_entry *entry,
 
   return (struct bfd_hash_entry *) ret;
 }
-
-/* This function is called for each input file from the add_symbols
-   pass of the linker.  */
+
+/*
+INTERNAL_FUNCTION
+	_bfd_link_section_stabs
+
+SYNOPSIS
+	bool _bfd_link_section_stabs
+	  (bfd *, struct stab_info *, asection *, asection *, void **,
+	   bfd_size_type *);
+
+DESCRIPTION
+	This function is called for each input file from the add_symbols
+	pass of the linker.
+*/
 
 bool
 _bfd_link_section_stabs (bfd *abfd,
@@ -500,11 +527,20 @@ _bfd_link_section_stabs (bfd *abfd,
   free (stabstrbuf);
   return false;
 }
-
-/* This function is called for each input file before the stab
-   section is relocated.  It discards stab entries for discarded
-   functions and variables.  The function returns TRUE iff
-   any entries have been deleted.
+
+/*
+INTERNAL_FUNCTION
+	_bfd_discard_section_stabs
+
+SYNOPSIS
+	bool _bfd_discard_section_stabs
+	  (bfd *, asection *, void *, bool (*) (bfd_vma, void *), void *);
+
+DESCRIPTION
+	This function is called for each input file before the stab
+	section is relocated.  It discards stab entries for discarded
+	functions and variables.  The function returns TRUE iff
+	any entries have been deleted.
 */
 
 bool
@@ -652,8 +688,18 @@ _bfd_discard_section_stabs (bfd *abfd,
   return false;
 }
 
-/* Write out the stab section.  This is called with the relocated
-   contents.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_write_section_stabs
+
+SYNOPSIS
+	bool _bfd_write_section_stabs
+	  (bfd *, struct stab_info *, asection *, void **, bfd_byte *);
+
+DESCRIPTION
+	Write out the stab section.  This is called with the relocated
+	contents.
+*/
 
 bool
 _bfd_write_section_stabs (bfd *output_bfd,
@@ -724,7 +770,16 @@ _bfd_write_section_stabs (bfd *output_bfd,
 				   stabsec->size);
 }
 
-/* Write out the .stabstr section.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_write_stab_strings
+
+SYNOPSIS
+	bool _bfd_write_stab_strings (bfd *, struct stab_info *);
+
+DESCRIPTION
+	Write out the .stabstr section.
+*/
 
 bool
 _bfd_write_stab_strings (bfd *output_bfd, struct stab_info *sinfo)
@@ -753,9 +808,18 @@ _bfd_write_stab_strings (bfd *output_bfd, struct stab_info *sinfo)
   return true;
 }
 
-/* Adjust an address in the .stab section.  Given OFFSET within
-   STABSEC, this returns the new offset in the adjusted stab section,
-   or -1 if the address refers to a stab which has been removed.  */
+/*
+INTERNAL_FUNCTION
+	_bfd_stab_section_offset
+
+SYNOPSIS
+	bfd_vma _bfd_stab_section_offset (asection *, void *, bfd_vma);
+
+DESCRIPTION
+	Adjust an address in the .stab section.  Given OFFSET within
+	STABSEC, this returns the new offset in the adjusted stab section,
+	or -1 if the address refers to a stab which has been removed.
+*/
 
 bfd_vma
 _bfd_stab_section_offset (asection *stabsec,
diff --git a/bfd/syms.c b/bfd/syms.c
index c460e377723..57ac52f8faa 100644
--- a/bfd/syms.c
+++ b/bfd/syms.c
@@ -168,19 +168,12 @@ DOCDD
 INODE
 typedef asymbol, symbol handling functions, Mini Symbols, Symbols
 
-*/
-/*
 SUBSECTION
 	typedef asymbol
 
 	An <<asymbol>> has the form:
 
-*/
-
-/*
 CODE_FRAGMENT
-
-.
 .typedef struct bfd_symbol
 .{
 .  {* A pointer to the BFD which owns the symbol. This information
@@ -327,6 +320,28 @@ CODE_FRAGMENT
 .}
 .asymbol;
 .
+
+EXTERNAL
+.typedef enum bfd_print_symbol
+.{
+.  bfd_print_symbol_name,
+.  bfd_print_symbol_more,
+.  bfd_print_symbol_all
+.} bfd_print_symbol_type;
+.
+.{* Information about a symbol that nm needs.  *}
+.
+.typedef struct _symbol_info
+.{
+.  symvalue value;
+.  char type;
+.  const char *name;		{* Symbol name.  *}
+.  unsigned char stab_type;	{* Stab type.  *}
+.  char stab_other;		{* Stab other.  *}
+.  short stab_desc;		{* Stab desc.  *}
+.  const char *stab_name;	{* String for stab type.  *}
+.} symbol_info;
+.
 */
 
 #include "sysdep.h"
diff --git a/bfd/targets.c b/bfd/targets.c
index 44fb5a32c74..021c808f62d 100644
--- a/bfd/targets.c
+++ b/bfd/targets.c
@@ -148,6 +148,7 @@ DESCRIPTION
 	the entry points which call them. Too bad we can't have one
 	macro to define them both!
 
+EXTERNAL
 .enum bfd_flavour
 .{
 .  {* N.B. Update bfd_flavour_name if you change this.  *}
@@ -173,14 +174,12 @@ DESCRIPTION
 .
 .enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN };
 .
-.{* Forward declaration.  *}
-.typedef struct bfd_link_info _bfd_link_info;
-.
-.{* Forward declaration.  *}
-.typedef struct flag_info flag_info;
-.
+.{* Forward declarations.  *}
+.struct flag_info;
 .typedef void (*bfd_cleanup) (bfd *);
 .
+
+CODE_FRAGMENT
 .typedef struct bfd_target
 .{
 .  {* Identifies the kind of target, e.g., SunOS4, Ultrix, etc.  *}
@@ -258,9 +257,10 @@ DESCRIPTION
 .  {* Write cached information into a file being written, at <<bfd_close>>.  *}
 .  bool (*_bfd_write_contents[bfd_type_end]) (bfd *);
 .
+
 The general target vector.  These vectors are initialized using the
 BFD_JUMP_TABLE macros.
-.
+
 .  {* Generic entry points.  *}
 .#define BFD_JUMP_TABLE_GENERIC(NAME) \
 .  NAME##_close_and_cleanup, \
@@ -1471,7 +1471,7 @@ static const struct targmatch bfd_target_match[] = {
 };
 
 /*
-CODE_FRAGMENT
+INTERNAL
 .{* Cached _bfd_check_format messages are put in this.  *}
 .struct per_xvec_message
 .{
diff --git a/gas/obj.h b/gas/obj.h
index e1036928cc2..6d92c368a56 100644
--- a/gas/obj.h
+++ b/gas/obj.h
@@ -37,6 +37,8 @@ void obj_symbol_to_chars (char **where, symbolS * symbolP);
 
 extern const pseudo_typeS obj_pseudo_table[];
 
+struct ecoff_extr;
+
 struct format_ops {
   int flavor;
   unsigned dfl_leading_underscore : 1;
