Even more documentation

1 files changed, 163 insertions, 150 deletions

diff --git a/bfd/bfd.c b/bfd/bfd.c
index 1e6d49b..d47a528 100644
--- a/bfd/bfd.c
+++ b/bfd/bfd.c
@@ -20,142 +20,143 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
 /* $Id$ */
 
-/*proto*
-@section @code{typedef bfd}
+/*
+SECTION
+	<<typedef bfd>>
 
-A BFD is has type @code{bfd}; objects of this type are the cornerstone
-of any application using @code{libbfd}. References though the BFD and
-to data in the BFD give the entire BFD functionality.
+DESCRIPTION
+	A BFD is has type <<bfd>>; objects of this type are the
+	cornerstone of any application using <<libbfd>>. References
+	though the BFD and to data in the BFD give the entire BFD
+	functionality.
 
-Here is the struct used to define the type @code{bfd}.  This contains
-the major data about the file, and contains pointers to the rest of
-the data.
+	Here is the struct used to define the type <<bfd>>.  This
+	contains he major data about the file, and contains pointers
+	to the rest of the data.
 
-*+++
+.struct _bfd 
+.{
+	The filename the application opened the BFD with.
 
-$struct _bfd 
-${
-  The filename the application opened the BFD with.
+.  CONST char *filename;                
 
-$  CONST char *filename;                
+	A pointer to the target jump table.
 
-A pointer to the target jump table.
+.  struct bfd_target *xvec;
 
-$  struct bfd_target *xvec;
+	To avoid dragging too many header files into every file that
+	includes @file{bfd.h}, IOSTREAM has been declared as a "char
+	*", and MTIME as a "long".  Their correct types, to which they
+	are cast when used, are "FILE *" and "time_t".    The iostream
+	is the result of an fopen on the filename. 
 
-
-To avoid dragging too many header files into every file that
-includes @file{bfd.h}, IOSTREAM has been declared as a "char *", and MTIME
-as a "long".  Their correct types, to which they are cast when used,
-are "FILE *" and "time_t".  
-
-The iostream is the result of an fopen on the filename.
-
-$  char *iostream;
+.  char *iostream;
 
 Is the file being cached @xref{File Caching}.
 
-$  boolean cacheable;
+.  boolean cacheable;
+
+	Marks whether there was a default target specified when the
+	BFD was opened. This is used to select what matching algorithm
+	to use to chose the back end.
 
-Marks whether there was a default target specified when the BFD was
-opened. This is used to select what matching algorithm to use to chose
-the back end.
+.  boolean target_defaulted;
 
-$  boolean target_defaulted;
+	The caching routines use these to maintain a
+	least-recently-used list of BFDs (@pxref{File Caching}).
 
-The caching routines use these to maintain a least-recently-used list of
-BFDs (@pxref{File Caching}).
+.  struct _bfd *lru_prev, *lru_next;
 
-$  struct _bfd *lru_prev, *lru_next;
+	When a file is closed by the caching routines, BFD retains
+	state information on the file here:
 
-When a file is closed by the caching routines, BFD retains state
-information on the file here:
+.  file_ptr where;              
 
-$  file_ptr where;              
+	and here:
 
-and here:
+.  boolean opened_once;
 
-$  boolean opened_once;
+.  boolean mtime_set;
 
-$  boolean mtime_set;
 File modified time 
 
-$  long mtime;          
+.  long mtime;          
 
-Reserved for an unimplemented file locking extension.
+	Reserved for an unimplemented file locking extension.
 
-$int ifd;
+.  int ifd;
 
-The format which belongs to the BFD.
+	The format which belongs to the BFD.
 
-$  bfd_format format;
+.  bfd_format format;
 
-The direction the BFD was opened with
+	The direction the BFD was opened with
 
-$  enum bfd_direction {no_direction = 0,
-$                       read_direction = 1,
-$                       write_direction = 2,
-$                       both_direction = 3} direction;
+.  enum bfd_direction {no_direction = 0,
+.                       read_direction = 1,
+.                       write_direction = 2,
+.                       both_direction = 3} direction;
 
-Format_specific flags
+	Format_specific flags
 
-$  flagword flags;              
+.  flagword flags;              
 
-Currently my_archive is tested before adding origin to anything. I
-believe that this can become always an add of origin, with origin set
-to 0 for non archive files.  
+	Currently my_archive is tested before adding origin to
+	anything. I believe that this can become always an add of
+	origin, with origin set to 0 for non archive files.  
 
-$  file_ptr origin;             
+.  file_ptr origin;             
 
-Remember when output has begun, to stop strange things happening.
+	Remember when output has begun, to stop strange things happening.
 
-$  boolean output_has_begun;
+.  boolean output_has_begun;
 
-Pointer to linked list of sections
+	Pointer to linked list of sections
 
-$  struct sec  *sections;
+.  struct sec  *sections;
 
-The number of sections 
+	The number of sections 
 
-$  unsigned int section_count;
+.  unsigned int section_count;
 
-Stuff only useful for object files:
-The start address.
+	Stuff only useful for object files: 
+	The start address.
 
-$  bfd_vma start_address;
-Used for input and output
+.  bfd_vma start_address;
 
-$  unsigned int symcount;
-Symbol table for output BFD
+	Used for input and output
 
-$  struct symbol_cache_entry  **outsymbols;             
+.  unsigned int symcount;
 
-Pointer to structure which contains architecture information
+	Symbol table for output BFD
 
-$  struct bfd_arch_info *arch_info;
+.  struct symbol_cache_entry  **outsymbols;             
 
-Stuff only useful for archives:
+	Pointer to structure which contains architecture information
 
-$  PTR arelt_data;              
-$  struct _bfd *my_archive;     
-$  struct _bfd *next;           
-$  struct _bfd *archive_head;   
-$  boolean has_armap;           
+.  struct bfd_arch_info *arch_info;
 
-Used by the back end to hold private data.
+	Stuff only useful for archives:
 
-$  PTR tdata;
+.  PTR arelt_data;              
+.  struct _bfd *my_archive;     
+.  struct _bfd *next;           
+.  struct _bfd *archive_head;   
+.  boolean has_armap;           
 
-Used by the application to hold private data
+	Used by the back end to hold private data.
 
-$  PTR usrdata;
+.  PTR tdata;
 
-Where all the allocated stuff under this BFD goes (@pxref{Memory Usage}).
+	Used by the application to hold private data
 
-$  struct obstack memory;
-$};
+.  PTR usrdata;
 
-*---
+	Where all the allocated stuff under this BFD goes
+	(@pxref{Memory Usage}).
+
+.  struct obstack memory;
+.};
 
 */
 #include "bfd.h"
@@ -338,12 +339,19 @@ int line;
 }
 
 
-/*proto* bfd_set_start_address
+/*
+FUNCTION
+	bfd_set_start_address
+
+DESCRIPTION
+
+	Marks the entry point of an output BFD.
 
-Marks the entry point of an output BFD. Returns @code{true} on
-success, @code{false} otherwise.
+RETURNS
+	Returns <<true>> on success, <<false>> otherwise.
 
-*; PROTO(boolean, bfd_set_start_address,(bfd *, bfd_vma));
+SYNOPSIS
+ 	boolean bfd_set_start_address(bfd *, bfd_vma);
 */
 
 boolean
@@ -356,14 +364,18 @@ bfd_vma vma;
 }
 
 
-/*proto*  bfd_get_mtime
+/*
+FUNCTION
+	bfd_get_mtime
 
-Return cached file modification time (e.g. as read from archive header
-for archive members, or from file system if we have been called
-before); else determine modify time, cache it, and return it.  
-
-*; PROTO(long, bfd_get_mtime, (bfd *));
+DESCRIPTION
+	Return cached file modification time (e.g. as read from
+	archive header for archive members, or from file system if we
+	have been called before); else determine modify time, cache
+	it, and return it.  
 
+SYNOPSIS
+	long bfd_get_mtime(bfd *);
 */
 
 long
@@ -385,63 +397,64 @@ bfd_get_mtime (abfd)
   return abfd->mtime;
 }
 
-/*proto* stuff
-
-*+
-
-#define bfd_sizeof_headers(abfd, reloc) \
-     BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
-
-#define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \
-     BFD_SEND (abfd, _bfd_find_nearest_line,  (abfd, section, symbols, offset, filename_ptr, func, line_ptr))
-
-#define bfd_debug_info_start(abfd) \
-        BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
-
-#define bfd_debug_info_end(abfd) \
-        BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
-
-#define bfd_debug_info_accumulate(abfd, section) \
-        BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
-
-#define bfd_stat_arch_elt(abfd, stat) \
-        BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
-
-#define bfd_coff_swap_aux_in(a,e,t,c,i) \
-        BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
-
-#define bfd_coff_swap_sym_in(a,e,i) \
-        BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
-
-#define bfd_coff_swap_lineno_in(a,e,i) \
-        BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
-
-#define bfd_set_arch_mach(abfd, arch, mach)\
-        BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
-
-#define bfd_coff_swap_reloc_out(abfd, i, o) \
-        BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o))
-
-#define bfd_coff_swap_lineno_out(abfd, i, o) \
-        BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o))
-
-#define bfd_coff_swap_aux_out(abfd, i, t,c,o) \
-        BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o))
-
-#define bfd_coff_swap_sym_out(abfd, i,o) \
-        BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o))
-
-#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
-        BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o))
-
-#define bfd_coff_swap_filehdr_out(abfd, i,o) \
-        BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o))
-
-#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
-        BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o))
-
-*-
-
+/*
+FUNCTION
+	stuff
+
+DESCRIPTION
+	stuff which should be documented
+
+.#define bfd_sizeof_headers(abfd, reloc) \
+.     BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
+.
+.#define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \
+.     BFD_SEND (abfd, _bfd_find_nearest_line,  (abfd, section, symbols, offset, filename_ptr, func, line_ptr))
+.
+.#define bfd_debug_info_start(abfd) \
+.        BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
+.
+.#define bfd_debug_info_end(abfd) \
+.        BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
+.
+.#define bfd_debug_info_accumulate(abfd, section) \
+.        BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
+.
+.#define bfd_stat_arch_elt(abfd, stat) \
+.        BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
+.
+.#define bfd_coff_swap_aux_in(a,e,t,c,i) \
+.        BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
+.
+.#define bfd_coff_swap_sym_in(a,e,i) \
+.        BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
+.
+.#define bfd_coff_swap_lineno_in(a,e,i) \
+.        BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
+.
+.#define bfd_set_arch_mach(abfd, arch, mach)\
+.        BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
+.
+.#define bfd_coff_swap_reloc_out(abfd, i, o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o))
+.
+.#define bfd_coff_swap_lineno_out(abfd, i, o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o))
+.
+.#define bfd_coff_swap_aux_out(abfd, i, t,c,o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o))
+.
+.#define bfd_coff_swap_sym_out(abfd, i,o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o))
+.
+.#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o))
+.
+.#define bfd_coff_swap_filehdr_out(abfd, i,o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o))
+.
+.#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
+.        BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o))
+.
 */