* aoutx.h, archive.c, archures.c, bfd.c, cache.c, coff-m88k.c,

	 coffcode.h, core.c, ctor.c, elf.c, format.c, ieee.c, init.c,
	 libbfd.c, libbfd.h, libcoff.h, opncls.c, reloc.c, section.c,
	 srec.c, syms.c, targets.c : all new documentation and lint
	 removal.

5 files changed, 114 insertions, 245 deletions

diff --git a/bfd/coffcode.h b/bfd/coffcode.h
index 6f1af86..dd8151d 100644
--- a/bfd/coffcode.h
+++ b/bfd/coffcode.h
@@ -23,7 +23,6 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 SECTION
 	coff backends
 
-DESCRIPTION
 	BFD supports a number of different flavours of coff format.
 	The major difference between formats are the sizes and
 	alignments of fields in structures on disk, and the occasional
@@ -51,7 +50,6 @@ DESCRIPTION
 SUBSECTION
 	Porting To A New Version of Coff
 
-DESCRIPTION
 	The recommended method is to select from the existing
 	implimentations the version of coff which is most like the one
 	you want to use, for our purposes, we'll say that i386 coff is
@@ -80,7 +78,6 @@ SUBSECTION
 SUBSUBSECTION
 	Bit Twiddling
 
-DESCRIPTION
 	Each flavour of coff supported in BFD has its own header file
 	descibing the external layout of the structures. There is also
 	an internal description of the coff layout (in
@@ -116,7 +113,6 @@ DESCRIPTION
 SUBSUBSECTION
 	Symbol Reading
 
-DESCRIPTION
 	The simple canonical form for symbols used by BFD is not rich
 	enough to keep all the information available in a coff symbol
 	table. The back end gets around this by keeping the original
@@ -134,7 +130,7 @@ DESCRIPTION
 	pointer to another structure in the symbol table at one moment
 	may be the size in bytes of a structure in the next.  Another
 	pass is made over the table. All symbols which mark file names
-	(@code{C_FILE} symbols) are modified so that the internal
+	(<<C_FILE>> symbols) are modified so that the internal
 	string points to the value in the auxent (the real filename)
 	rather than the normal text associated with the symbol
 	(@code{".file"}). 
@@ -159,8 +155,6 @@ DESCRIPTION
 SUBSUBSECTION
 	Symbol Writing
 
-
-DESCRIPTION
 	Writing a symbol to a coff file which didn't come from a coff
 	file will lose any debugging information. The @code{asymbol}
 	structure remembers the BFD from which was born, and on output
@@ -175,8 +169,6 @@ DESCRIPTION
 	the linker to accumulate and output large symbol tables
 	without having to do too much byte copying.
 
-
-
 	This function runs through the provided symbol table and
 	patches each symbol marked as a file place holder
 	(@code{C_FILE}) to point to the next file place holder in the
@@ -195,6 +187,7 @@ DESCRIPTION
 	@code{asection} @xref{Sections}. 
 
 	o coff_mangle_symbols
+
 	This routine runs though the provided symbol table and uses
 	the offsets generated by the previous pass and the pointers
 	generated when the symbol table was read in to create the
@@ -203,6 +196,7 @@ DESCRIPTION
 	being referenced. 
 
 	o coff_write_symbols
+
 	This routine runs through the symbol table and patches up the
 	symbols from their internal form into the coff way, calls the
 	bit twiddlers and writes out the tabel to the file. 
@@ -210,56 +204,53 @@ DESCRIPTION
 */
 
 /*
-INTERNAL
-
+INTERNAL_DEFINITION
+	coff_symbol_type
 
+DESCRIPTION
 	The hidden information for an asymbol is described in a
 	coff_ptr_struct, which is typedefed to a combined_entry_type
 
-	.typedef struct coff_ptr_struct 
-	.{
-
-	Remembers the offset from the first symbol in the file for
-	this symbol. Generated by @code{coff_renumber_symbols}.
-
-	.unsigned int offset;
-
-	Should the tag field of this symbol be renumbered.
-	Created by @code{coff_pointerize_aux}.
-
-	.char fix_tag;
-
-	Should the endidx field of this symbol be renumbered.
-	Created by @code{coff_pointerize_aux}.
-
-	.char fix_end;
-
-	The container for the symbol structure as read and translated
-	from the file.
-
-	.union {
-	.   union internal_auxent auxent;
-	.   struct internal_syment syment;
-	. } u;
-	.} combined_entry_type;
-
-	Each canonical asymbol really looks like this:
-
-	.typedef struct coff_symbol_struct
-	.{
-
-	The actual symbol which the rest of BFD works with
-
-	.asymbol symbol;
-
-	A pointer to the hidden information for this symbol
-
-	.combined_entry_type *native;
-
-	A pointer to the linenumber information for this symbol
-
-	.struct lineno_cache_entry *lineno;
-	.} coff_symbol_type;
+CODE_FRAGMENT
+.typedef struct coff_ptr_struct 
+.{
+.
+.       {* Remembers the offset from the first symbol in the file for
+.          this symbol. Generated by coff_renumber_symbols. *}
+.unsigned int offset;
+.
+.       {* Should the tag field of this symbol be renumbered.
+.          Created by coff_pointerize_aux. *}
+.char fix_tag;
+.
+.       {* Should the endidx field of this symbol be renumbered.
+.          Created by coff_pointerize_aux. *}
+.char fix_end;
+.
+.       {* The container for the symbol structure as read and translated
+.           from the file. *}
+.
+.union {
+.   union internal_auxent auxent;
+.   struct internal_syment syment;
+. } u;
+.} combined_entry_type;
+.
+.
+.{* Each canonical asymbol really looks like this: *}
+.
+.typedef struct coff_symbol_struct
+.{
+.   {* The actual symbol which the rest of BFD works with *}
+.asymbol symbol;
+.
+.   {* A pointer to the hidden information for this symbol *}
+.combined_entry_type *native;
+.
+.   {* A pointer to the linenumber information for this symbol *}
+.struct lineno_cache_entry *lineno;
+.
+.} coff_symbol_type;
 
 
 */
@@ -1658,7 +1649,6 @@ DEFUN(coff_write_symbols,(abfd),
 SUBSUBSECTION
 	Writing Relocations
 
-DESCRIPTION
 	To write relocations, all the back end does is step though the
 	canonical relocation table, and create an
 	@code{internal_reloc}. The symbol index to use is removed from
@@ -1836,7 +1826,7 @@ fprintf(file,"[%3d]",
 	      fprintf(file, "File ");
 	      break;
 	    default:
-	      fprintf(file, "AUX tv %x lnno %x size %x",
+	      fprintf(file, "AUX lnno %x size %x",
 		      combined[aux+1].u.auxent.x_sym.x_misc.x_lnsz.x_lnno,
 		      combined[aux+1].u.auxent.x_sym.x_misc.x_lnsz.x_size);
 	      break;
@@ -2720,7 +2710,6 @@ DEFUN(section_from_bfd_index,(abfd, index),
 SUBSUBSECTION 
 	Reading Linenumbers
 
-DESCRIPTION
 	Creating the linenumber table is done by reading in the entire
 	coff linenumber table, and creating another table for internal use.
 
@@ -3081,7 +3070,6 @@ sec_ptr         asect;
 SUBSUBSECTION 
 	Reading Relocations
 
-DESCRIPTION
 	Coff relocations are easily transformed into the internal BFD form
 	(@code{arelent}).
 
@@ -3159,19 +3147,25 @@ DEFUN(coff_slurp_reloc_table,(abfd, asect, symbols),
   
   for (idx = 0; idx < asect->reloc_count; idx ++) 
   {
+#ifdef RELOC_PROCESSING
       struct internal_reloc dst;
-      asymbol        *ptr;
       struct external_reloc  *src;
 
       cache_ptr = reloc_cache + idx;
       src = native_relocs + idx;
-
       bfd_swap_reloc_in(abfd, src, &dst);
 
-
-#ifdef RELOC_PROCESSING
       RELOC_PROCESSING(cache_ptr, &dst, symbols, abfd, asect);
 #else
+      struct internal_reloc dst;
+      asymbol        *ptr;
+      struct external_reloc  *src;
+
+      cache_ptr = reloc_cache + idx;
+      src = native_relocs + idx;
+
+      bfd_swap_reloc_in(abfd, src, &dst);
+
 
       cache_ptr->address = dst.r_vaddr;
 
diff --git a/bfd/core.c b/bfd/core.c
index 993df11..c428775 100644
--- a/bfd/core.c
+++ b/bfd/core.c
@@ -35,12 +35,13 @@ DESCRIPTION
 FUNCTION
 	bfd_core_file_failing_command
 
+SYNOPSIS
+	CONST char *bfd_core_file_failing_command(bfd *);
+
 DESCRIPTION
 	Returns a read-only string explaining what program was running
 	when it failed and produced the core file being read
 
-SYNOPSIS
-	CONST char *bfd_core_file_failing_command(bfd *);
 */
 
 CONST char *
@@ -58,12 +59,12 @@ DEFUN(bfd_core_file_failing_command,(abfd),
 FUNCTION
 	bfd_core_file_failing_signal
 
+SYNOPSIS
+	int bfd_core_file_failing_signal(bfd *);
+
 DESCRIPTION
 	Returns the signal number which caused the core dump which
 	generated the file the BFD is attached to.
-
-SYNOPSIS
-	int bfd_core_file_failing_signal(bfd *);
 */
 
 int
@@ -82,16 +83,15 @@ bfd_core_file_failing_signal (abfd)
 FUNCTION
 	core_file_matches_executable_p
 
+SYNOPSIS
+	boolean core_file_matches_executable_p
+		(bfd *core_bfd, bfd *exec_bfd);
+
 DESCRIPTION
 	Returns <<true>> if the core file attached to @var{core_bfd}
 	was generated by a run of the executable file attached to
 	@var{exec_bfd}, or else <<false>>.
-
-SYNOPSIS
-	boolean core_file_matches_executable_p
-		(bfd *core_bfd, bfd *exec_bfd);
 */
-
 boolean
 core_file_matches_executable_p (core_bfd, exec_bfd)
      bfd *core_bfd, *exec_bfd;
diff --git a/bfd/ctor.c b/bfd/ctor.c
index 5aa75b7..1bcb49c 100644
--- a/bfd/ctor.c
+++ b/bfd/ctor.c
@@ -25,7 +25,6 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 SECTION
 	Constructors
 
-DESCRIPTION
 	Classes in C++ have 'constructors' and 'destructors'.  These
 	are functions which are called automatically by the language
 	whenever data of a class is created or destroyed.  Class data
@@ -92,9 +91,15 @@ DESCRIPTION
 
 
 /*
-INTERNAL FUNCTION
+INTERNAL_FUNCTION
 	bfd_constructor_entry 
 
+SYNOPSIS
+	void bfd_constructor_entry(bfd *abfd, 
+		asymbol **symbol_ptr_ptr,
+		CONST char*type);
+
+
 DESCRIPTION
 	This function is called with an a symbol describing the
 	function to be called, an string which descibes the xtor type,
@@ -104,11 +109,6 @@ DESCRIPTION
 	have one, and grow a relocation table for the entry points as
 	they accumulate.
 
-SYNOPSIS
-	void bfd_constructor_entry(bfd *abfd, 
-		asymbol **symbol_ptr_ptr,
-		CONST char*type);
-
 */
 
  
diff --git a/bfd/libcoff.h b/bfd/libcoff.h
index b666e2e..94a5664 100644
--- a/bfd/libcoff.h
+++ b/bfd/libcoff.h
@@ -35,26 +35,6 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 #define obj_symbol_slew(bfd) 0
 #endif
 
-#if 0
-typedef struct coff_ptr_struct
-{
-  unsigned int offset;
-  char fix_tag;
-  char fix_end;
-  union {
-    union internal_auxent auxent;
-    struct internal_syment syment;
-  } u;
-} combined_entry_type;
-
-
-typedef struct 
-{
-  asymbol symbol;
-  combined_entry_type *native;
-  struct lineno_cache_entry *lineno;
-} coff_symbol_type;
-#endif
 
 /* `Tdata' information kept for COFF files.  */
 
@@ -93,23 +73,43 @@ typedef struct coff_tdata
 
 
 
-/*THE FOLLOWING IS EXTRACTED FROM THE SOURCE*/
+/* And more taken from the source .. */
 
-/*:coffcode.h*/
-typedef struct coff_ptr_struct 
 {
+
+        /* Remembers the offset from the first symbol in the file for
+          this symbol. Generated by coff_renumber_symbols. */
 unsigned int offset;
+
+        /* Should the tag field of this symbol be renumbered.
+          Created by coff_pointerize_aux. */
 char fix_tag;
+
+        /* Should the endidx field of this symbol be renumbered.
+          Created by coff_pointerize_aux. */
 char fix_end;
+
+        /* The container for the symbol structure as read and translated
+           from the file. */
+
 union {
    union internal_auxent auxent;
    struct internal_syment syment;
  } u;
 } combined_entry_type;
+
+
+ /* Each canonical asymbol really looks like this: */
+
 typedef struct coff_symbol_struct
 {
+    /* The actual symbol which the rest of BFD works with */
 asymbol symbol;
+
+    /* A pointer to the hidden information for this symbol */
 combined_entry_type *native;
+
+    /* A pointer to the linenumber information for this symbol */
 struct lineno_cache_entry *lineno;
-} coff_symbol_type;
 
+} coff_symbol_type;
diff --git a/bfd/targets.c b/bfd/targets.c
index 4e0bbcd..a843359 100644
--- a/bfd/targets.c
+++ b/bfd/targets.c
@@ -28,7 +28,6 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 SECTION 
 	Targets
 
-DESCRIPTION
 	Each port of BFD to a different machine requries the creation
 	of a target back end. All the back end provides to the root
 	part of BFD is a structure containing pointers to functions
@@ -79,7 +78,6 @@ DESCRIPTION
 SUBSECTION
 	bfd_target
 
-DESCRIPTION
 	This structure contains everything that BFD knows about a
 	target. It includes things like its byte order, name, what
 	routines to call to do various operations, etc.   
@@ -122,6 +120,7 @@ DESCRIPTION
 	the entry points which call them. Too bad we can't have one
 	macro to define them both! 
 
+
 .typedef struct bfd_target
 .{
 
@@ -330,12 +329,12 @@ Special entry points for gas to swap coff parts
 
 */
 
-/* The default is to define a target_vector containing just the
-   DEFAULT_TARGET.  (This is to save space in the executables.)
-   You can override this by giving an explicit target_vector using
-   the SELECT_VECTOR macro.
-   Or define ALL_TARGETS macro to get all of the available targets. */
-   
+/* The default is to define a target_vector containing all the targets.
+   By setting MINIMIZE=1 on the "make" command line, the user can change this
+   to a vector containing just DEFAULT_VECTOR and any required
+   traditional-core-file handler.  (This is to save space in the executables.)
+   The config files can also override the default large vector by giving an
+   explicit SELECT_VECS macro.  */
 
 #if MINIMIZE && defined(DEFAULT_VECTOR) && !defined(SELECT_VECS)
 #ifdef TRAD_CORE
@@ -345,6 +344,8 @@ Special entry points for gas to swap coff parts
 #endif
 #endif
 
+/* All known xvecs.  They are listed a second time below, since
+   we can't intermix extern's and initializers.  */
 extern bfd_target ecoff_little_vec;
 extern bfd_target ecoff_big_vec;
 extern bfd_target sunos_big_vec;
@@ -374,141 +375,15 @@ extern bfd_target DEFAULT_VECTOR;
 #ifdef SELECT_VECS
 
 bfd_target *target_vector[] = {
-SELECT_VECS,
-0
-
+	&icoff_little_vec,
+	0
 };
-#else
-
-#ifdef GNU960
-#define ICOFF_LITTLE_VEC        icoff_little_vec
-#define ICOFF_BIG_VEC           icoff_big_vec
-#define B_OUT_VEC_LITTLE_HOST   b_out_vec_little_host
-#define B_OUT_VEC_BIG_HOST      b_out_vec_big_host
-#endif /* GNU960 */
-
-#ifndef RESTRICTED
-#define ECOFF_LITTLE_VEC        ecoff_little_vec
-#define ECOFF_BIG_VEC           ecoff_big_vec
-#define ICOFF_LITTLE_VEC        icoff_little_vec
-#define ICOFF_BIG_VEC           icoff_big_vec
-#define ELF_LITTLE_VEC		elf_little_vec
-#define ELF_BIG_VEC		elf_big_vec
-#define ZB_OUT_VEC_LITTLE_HOST  b_out_vec_little_host
-#define ZB_OUT_VEC_BIG_HOST     b_out_vec_big_host
-#define SUNOS_VEC_BIG_HOST      sunos_big_vec
-#define DEMO_64_VEC             demo_64_vec
-
-/* We have no oasys tools anymore, so we can't test any of this
-   anymore. If you want to test the stuff yourself, go ahead...
-   steve@cygnus.com */
-#if 0
-#define OASYS_VEC               oasys_vec
-#endif
 
-#define IEEE_VEC                ieee_vec
-#define M88KBCS_VEC            m88kbcs_vec
-#define SREC_VEC                srec_vec
-#define M68KCOFF_VEC            m68kcoff_vec
-#define I386COFF_VEC            i386coff_vec
-#define	I386AOUT_VEC		i386aout_vec
-#define A29KCOFF_BIG_VEC	a29kcoff_big_vec
-#define RS6000COFF_VEC		rs6000coff_vec
-#define H8300COFF_VEC           h8300coff_vec
-#endif
+#else
 
 bfd_target *target_vector[] = {
-
-#ifdef DEFAULT_VECTOR
-        &DEFAULT_VECTOR,
-#endif
-
-#ifdef  I386COFF_VEC
-        &I386COFF_VEC,
-#endif
-
-#ifdef	I386AOUT_VEC
-	&I386AOUT_VEC,
-#endif
-
-#ifdef ECOFF_LITTLE_VEC
-        &ECOFF_LITTLE_VEC,
-#endif
-
-#ifdef ECOFF_BIG_VEC
-        &ECOFF_BIG_VEC,
-#endif
-
-#ifdef IEEE_VEC
-        &IEEE_VEC,
-#endif
-
-#ifdef OASYS_VEC
-        &OASYS_VEC,
-#endif
-
-#ifdef SUNOS_VEC_BIG_HOST
-        &SUNOS_VEC_BIG_HOST,
-#endif
-
-#ifdef HOST_64_BIT
-#ifdef DEMO_64_VEC
-        &DEMO_64_VEC,
-#endif
-#endif
-
-#ifdef H300COFF_VEC
-	&h8300coff_vec,
-#endif
-#ifdef M88KBCS_VEC
-        &M88KBCS_VEC,
-#endif
-
-#ifdef SREC_VEC
-        &SREC_VEC,
-#endif
-        
-#ifdef ICOFF_LITTLE_VEC
-        &ICOFF_LITTLE_VEC,
-#endif
-
-#ifdef ICOFF_BIG_VEC
-        &ICOFF_BIG_VEC,
-#endif
-
-#ifdef ELF_LITTLE_VEC
-        &ELF_LITTLE_VEC,
-#endif
-
-#ifdef ELF_BIG_VEC
-        &ELF_BIG_VEC,
-#endif
-
-#ifdef B_OUT_VEC_LITTLE_HOST
-        &B_OUT_VEC_LITTLE_HOST,
-#endif
-
-#ifdef B_OUT_VEC_BIG_HOST
-        &B_OUT_VEC_BIG_HOST,
-#endif
-
-#ifdef  M68KCOFF_VEC
-        &M68KCOFF_VEC,
-#endif
-
-#ifdef	A29KCOFF_BIG_VEC
-	&A29KCOFF_BIG_VEC,
-#endif
-
-#ifdef	TRAD_CORE
-	&trad_core_vec,
-#endif
-
-#ifdef  RS6000COFF_VEC
-	&RS6000COFF_VEC,
-#endif
-
-        NULL, /* end of list marker */
+	&icoff_little_vec,
+	NULL, /* end of list marker */
 };
 
 #endif
@@ -518,9 +393,9 @@ bfd_target *target_vector[] = {
 
 bfd_target *default_vector[] = {
 #ifdef DEFAULT_VECTOR
-        &DEFAULT_VECTOR,
+	&DEFAULT_VECTOR,
 #endif
-        0,
+	0,
 };