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, 105 insertions, 102 deletions

diff --git a/bfd/libbfd.h b/bfd/libbfd.h
index 3bd79d2..f56f2b8 100644
--- a/bfd/libbfd.h
+++ b/bfd/libbfd.h
@@ -1,7 +1,7 @@
 /* DO NOT EDIT!  -*- buffer-read-only: t -*-  This file is automatically
    generated from "libbfd-in.h", "libbfd.c", "bfd.c", "bfdio.c",
-   "bfdwin.c", "cache.c", "reloc.c", "section.c", "targets.c", "archures.c"
-   and "linker.c".
+   "archive.c", "archures.c", "bfdwin.c", "cache.c", "hash.c", "linker.c",
+   "opncls.c", "reloc.c", "section.c", "stabs.c" and "targets.c".
    Run "make headers" in your build bfd/ to regenerate.  */
 
 /* libbfd.h -- Declarations used by bfd library *implementation*.
@@ -176,10 +176,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;
@@ -220,8 +216,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
@@ -715,34 +709,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
@@ -768,31 +734,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
@@ -847,9 +788,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,
@@ -976,22 +918,22 @@ _bfd_malloc_and_read (bfd *abfd, bfd_size_type asize, bfd_size_type rsize)
   return NULL;
 }
 /* Extracted from libbfd.c.  */
-extern void * bfd_malloc (bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+void *bfd_malloc (bfd_size_type /*size*/) ATTRIBUTE_HIDDEN;
 
-extern void * bfd_realloc (void * MEM, bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+void *bfd_realloc (void */*mem*/, bfd_size_type /*size*/) ATTRIBUTE_HIDDEN;
 
-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*/) ATTRIBUTE_HIDDEN;
 
-extern void * bfd_zmalloc (bfd_size_type SIZE) ATTRIBUTE_HIDDEN;
+void *bfd_zmalloc (bfd_size_type /*size*/) ATTRIBUTE_HIDDEN;
 
-bool bfd_write_bigendian_4byte_int (bfd *, unsigned int);
+bool bfd_write_bigendian_4byte_int (bfd *, unsigned int) ATTRIBUTE_HIDDEN;
 
-unsigned int bfd_log2 (bfd_vma x);
+unsigned int bfd_log2 (bfd_vma x) ATTRIBUTE_HIDDEN;
 
 /* Extracted from bfd.c.  */
-bfd_error_handler_type _bfd_set_error_handler_caching (bfd *);
+bfd_error_handler_type _bfd_set_error_handler_caching (bfd *) ATTRIBUTE_HIDDEN;
 
-const char *_bfd_get_error_program_name (void);
+const char *_bfd_get_error_program_name (void) ATTRIBUTE_HIDDEN;
 
 /* Extracted from bfdio.c.  */
 struct bfd_iovec
@@ -1004,7 +946,7 @@ struct bfd_iovec
      or -1 (setting <<bfd_error>>) if an error occurs.  */
   file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes);
   file_ptr (*bwrite) (struct bfd *abfd, const void *ptr,
-                      file_ptr nbytes);
+		      file_ptr nbytes);
   /* Return the current IOSTREAM file offset, or -1 (setting <<bfd_error>>
      if an error occurs.  */
   file_ptr (*btell) (struct bfd *abfd);
@@ -1021,24 +963,79 @@ struct bfd_iovec
      MAP_LEN the size mapped (a page multiple).  Use unmap with MAP_ADDR and
      MAP_LEN to unmap.  */
   void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len,
-                  int prot, int flags, file_ptr offset,
-                  void **map_addr, bfd_size_type *map_len);
+		  int prot, int flags, file_ptr offset,
+		  void **map_addr, bfd_size_type *map_len);
 };
 extern const struct bfd_iovec _bfd_memory_iovec;
+
+/* Extracted from archive.c.  */
+/* 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.  */
+};
+
+/* Extracted from archures.c.  */
+extern const bfd_arch_info_type bfd_default_arch_struct;
+
+const bfd_arch_info_type *bfd_default_compatible
+   (const bfd_arch_info_type *a, const bfd_arch_info_type *b) ATTRIBUTE_HIDDEN;
+
+bool bfd_default_scan
+   (const struct bfd_arch_info *info, const char *string) ATTRIBUTE_HIDDEN;
+
+void *bfd_arch_default_fill (bfd_size_type count,
+    bool is_bigendian,
+    bool code) ATTRIBUTE_HIDDEN;
+
 /* Extracted from bfdwin.c.  */
-struct _bfd_window_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;
+
 /* Extracted from cache.c.  */
-bool bfd_cache_init (bfd *abfd);
+bool bfd_cache_init (bfd *abfd) ATTRIBUTE_HIDDEN;
+
+FILE* bfd_open_file (bfd *abfd) ATTRIBUTE_HIDDEN;
+
+/* Extracted from hash.c.  */
+struct bfd_strtab_hash *_bfd_stringtab_init (void) ATTRIBUTE_HIDDEN;
+
+struct bfd_strtab_hash *_bfd_xcoff_stringtab_init
+   (bool /*isxcoff64*/) ATTRIBUTE_HIDDEN;
+
+void _bfd_stringtab_free (struct bfd_strtab_hash *) ATTRIBUTE_HIDDEN;
+
+bfd_size_type _bfd_stringtab_add
+   (struct bfd_strtab_hash *, const char *,
+    bool /*hash*/, bool /*copy*/) ATTRIBUTE_HIDDEN;
+
+bfd_size_type _bfd_stringtab_size (struct bfd_strtab_hash *) ATTRIBUTE_HIDDEN;
+
+bool _bfd_stringtab_emit (bfd *, struct bfd_strtab_hash *) ATTRIBUTE_HIDDEN;
+
+/* Extracted from linker.c.  */
+bool _bfd_generic_verify_endian_match
+   (bfd *ibfd, struct bfd_link_info *info) ATTRIBUTE_HIDDEN;
+
+/* Extracted from opncls.c.  */
+bfd *_bfd_new_bfd (void) ATTRIBUTE_HIDDEN;
 
-bool bfd_cache_close (bfd *abfd);
+bfd *_bfd_new_bfd_contained_in (bfd *) ATTRIBUTE_HIDDEN;
 
-FILE* bfd_open_file (bfd *abfd);
+bool _bfd_free_cached_info (bfd *) ATTRIBUTE_HIDDEN;
 
 /* Extracted from reloc.c.  */
 #ifdef _BFD_MAKE_TABLE_bfd_reloc_code_real
@@ -3515,22 +3512,22 @@ static const char *const bfd_reloc_code_real_names[] = { "@@uninitialized@@",
 #endif
 
 reloc_howto_type *bfd_default_reloc_type_lookup
-   (bfd *abfd, bfd_reloc_code_real_type  code);
+   (bfd *abfd, bfd_reloc_code_real_type  code) ATTRIBUTE_HIDDEN;
 
 bool bfd_generic_relax_section
    (bfd *abfd,
     asection *section,
     struct bfd_link_info *,
-    bool *);
+    bool *) ATTRIBUTE_HIDDEN;
 
 bool bfd_generic_gc_sections
-   (bfd *, struct bfd_link_info *);
+   (bfd *, struct bfd_link_info *) ATTRIBUTE_HIDDEN;
 
 bool bfd_generic_lookup_section_flags
-   (struct bfd_link_info *, struct flag_info *, asection *);
+   (struct bfd_link_info *, struct flag_info *, asection *) ATTRIBUTE_HIDDEN;
 
 bool bfd_generic_merge_sections
-   (bfd *, struct bfd_link_info *);
+   (bfd *, struct bfd_link_info *) ATTRIBUTE_HIDDEN;
 
 bfd_byte *bfd_generic_get_relocated_section_contents
    (bfd *abfd,
@@ -3538,40 +3535,46 @@ bfd_byte *bfd_generic_get_relocated_section_contents
     struct bfd_link_order *link_order,
     bfd_byte *data,
     bool relocatable,
-    asymbol **symbols);
+    asymbol **symbols) ATTRIBUTE_HIDDEN;
 
 void _bfd_generic_set_reloc
    (bfd *abfd,
     sec_ptr section,
     arelent **relptr,
-    unsigned int count);
+    unsigned int count) ATTRIBUTE_HIDDEN;
 
 bool _bfd_unrecognized_reloc
    (bfd * abfd,
     sec_ptr section,
-    unsigned int r_type);
+    unsigned int r_type) ATTRIBUTE_HIDDEN;
 
 /* Extracted from section.c.  */
-bool _bfd_section_size_insane (bfd *abfd, asection *sec);
+bool _bfd_section_size_insane (bfd *abfd, asection *sec) ATTRIBUTE_HIDDEN;
 
-/* Extracted from targets.c.  */
-struct per_xvec_message **_bfd_per_xvec_warn (const bfd_target *, size_t);
+/* Extracted from stabs.c.  */
+bool _bfd_link_section_stabs
+   (bfd *, struct stab_info *, asection *, asection *, void **,
+    bfd_size_type *) ATTRIBUTE_HIDDEN;
 
-/* Extracted from archures.c.  */
-extern const bfd_arch_info_type bfd_default_arch_struct;
-const bfd_arch_info_type *bfd_default_compatible
-   (const bfd_arch_info_type *a, const bfd_arch_info_type *b);
+bool _bfd_discard_section_stabs
+   (bfd *, asection *, void *, bool (*) (bfd_vma, void *), void *) ATTRIBUTE_HIDDEN;
 
-bool bfd_default_scan
-   (const struct bfd_arch_info *info, const char *string);
+bool _bfd_write_section_stabs
+   (bfd *, struct stab_info *, asection *, void **, bfd_byte *) ATTRIBUTE_HIDDEN;
 
-void *bfd_arch_default_fill (bfd_size_type count,
-    bool is_bigendian,
-    bool code);
+bool _bfd_write_stab_strings (bfd *, struct stab_info *) ATTRIBUTE_HIDDEN;
 
-/* Extracted from linker.c.  */
-bool _bfd_generic_verify_endian_match
-   (bfd *ibfd, struct bfd_link_info *info);
+bfd_vma _bfd_stab_section_offset (asection *, void *, bfd_vma) ATTRIBUTE_HIDDEN;
+
+/* Extracted from targets.c.  */
+/* Cached _bfd_check_format messages are put in this.  */
+struct per_xvec_message
+{
+  struct per_xvec_message *next;
+  char message[];
+};
+
+struct per_xvec_message **_bfd_per_xvec_warn (const bfd_target *, size_t) ATTRIBUTE_HIDDEN;
 
 #ifdef __cplusplus
 }