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, 249 insertions, 23 deletions

diff --git a/bfd/hash.c b/bfd/hash.c
index add7d10..483593e 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)