Generated docs and include files

bfd/doc/chew.c extracts documentation from source code comments
annotated with keywords, and generates much of bfd.h and libbfd.h from
those same comments.  The docs have suffered from people (me too)
adding things like CODE_FRAGMENT to the source to put code into bfd.h
without realising that CODE_FRAGMENT also puts @example around said
code into the docs.  So we have random senseless things in the docs.
This patch fixes that problem (well, the senseless things from
CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a
few chew.c features.  libbfd.h now automatically gets ATTRIBUTE_HIDDEN
prototypes, and indentation in bfd.h and libbfd.h is better.

1 files changed, 59 insertions, 5 deletions

diff --git a/bfd/bfdwin.c b/bfd/bfdwin.c
index 49b751c..5ecf2f9 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;