[RFC] Use Doxygen for internals documentation

[RFC] Use Doxygen for internals documentation

[Stan Shebs]

[-- Attachment #1: Type: text/plain, Size: 2650 bytes --]

This patch is the third and final step in the transition away from the
old GDB internals manual.

It adds the use of Doxygen ( http://www.stack.nl/~dimitri/doxygen/ ),
perhaps the most widely-used documentation generator.  Doxygen combines
a basic source parser with an annotation scheme for comments, producing
a collection of web pages that is both API and cross-reference.  Doxygen
is already used by several GNU projects, including libstdc++ and Bison.

Doxygen will work on any random pile of source files, but it's more
effective if you set up a config file (a "Doxyfile") and tweak source
code comments; this patch sets up basic machinery and adds a bunch of
annotation to minsyms.h and utils.h, so people can get a feel for how
they like it.

To try it out, install doxygen, apply this patch to GDB, configure in
the usual way, then do

	make doxy

in the doc objdir.  This will produce a "doxy" subdir, with three
subdirs in turn, each based on a different config file:

	doxy/gdb-api - GDB's "API", basically what is in .h files
	doxy/gdb-xref - the full xref, voluminous
	doxy/gdbserver - GDBserver xref
	doxy/xml - XML version, for further script-crunching

To look at it, you can open a browser on any file, or start with the
index.html in each subdir, and then click around.  The directories are
large, because they have copies of the source files with lots of links
added.  (I found it very handy to go from sources to doc and back with
just a couple clicks.)

To see how the annotations work, look down through minsyms.h and
utils.h, you can see the comments attached to declarations.

Doxygen has some flaws for us:

1) Its parser get befuddled by some of our macrology.
2) It doesn't know about host/target configs, just indexes everything
   and then gets confused by multiple files with functions of the same
   name.
3) The only way I could find to get Emacs to preserve our current
   formatting rules is to have the opening "/**" on a line by itself.
4) Even the API-only version is large, and needs tweaking so that
   more-important headers are more visible.

Even so, with the minimal configuration here, I found the result to
be a useful way to navigate around all the sources, quickly look up
types, see what is used and what is not used.

So I think it's worth going ahead and introducing.  But of course
something like this only works if everybody signs on, patches are
required to have Doxygen annotations for header file additions, and
so forth.  Look at the header file changes, try noodling around the
Doxygen output, see if you're willing to be looking at all this for
the next N years.

Stan
stan@codesourcery.com

[-- Attachment #2: doxy-patch-1 --]
[-- Type: text/plain, Size: 48220 bytes --]

Index: minsyms.h
===================================================================
RCS file: /cvs/src/src/gdb/minsyms.h,v
retrieving revision 1.8
diff -p -r1.8 minsyms.h
*** minsyms.h	5 Aug 2013 15:51:02 -0000	1.8
--- minsyms.h	11 Oct 2013 21:19:31 -0000
***************
*** 20,43 ****
  #ifndef MINSYMS_H
  #define MINSYMS_H
  
! /* Several lookup functions return both a minimal symbol and the
     objfile in which it is found.  This structure is used in these
     cases.  */
  
  struct bound_minimal_symbol
  {
!   /* The minimal symbol that was found, or NULL if no minimal symbol
       was found.  */
  
    struct minimal_symbol *minsym;
  
!   /* If MINSYM is not NULL, then this is the objfile in which the
       symbol is defined.  */
  
    struct objfile *objfile;
  };
  
! /* This header declares most of the API for dealing with minimal
     symbols and minimal symbol tables.  A few things are declared
     elsewhere; see below.
  
--- 20,48 ----
  #ifndef MINSYMS_H
  #define MINSYMS_H
  
! /**
!    Several lookup functions return both a minimal symbol and the
     objfile in which it is found.  This structure is used in these
     cases.  */
  
  struct bound_minimal_symbol
  {
!   /**
!      The minimal symbol that was found, or NULL if no minimal symbol
       was found.  */
  
    struct minimal_symbol *minsym;
  
!   /**
!      If MINSYM is not NULL, then this is the objfile in which the
       symbol is defined.  */
  
    struct objfile *objfile;
  };
  
! /**
!    \page minimal-symbols Minimal Symbols
!    This header declares most of the API for dealing with minimal
     symbols and minimal symbol tables.  A few things are declared
     elsewhere; see below.
  
*************** struct bound_minimal_symbol
*** 53,66 ****
     as opaque and use functions provided by minsyms.c to inspect them.
  */
  
! /* Prepare to start collecting minimal symbols.  This should be called
     by a symbol reader to initialize the minimal symbol module.
     Currently, minimal symbol table creation is not reentrant; it
     relies on global (static) variables in minsyms.c.  */
  
  void init_minimal_symbol_collection (void);
  
! /* Return a cleanup which is used to clean up the global state left
     over by minimal symbol creation.  After calling
     init_minimal_symbol_collection, a symbol reader should call this
     function.  Then, after all minimal symbols have been read,
--- 58,73 ----
     as opaque and use functions provided by minsyms.c to inspect them.
  */
  
! /**
!    Prepare to start collecting minimal symbols.  This should be called
     by a symbol reader to initialize the minimal symbol module.
     Currently, minimal symbol table creation is not reentrant; it
     relies on global (static) variables in minsyms.c.  */
  
  void init_minimal_symbol_collection (void);
  
! /**
!    Return a cleanup which is used to clean up the global state left
     over by minimal symbol creation.  After calling
     init_minimal_symbol_collection, a symbol reader should call this
     function.  Then, after all minimal symbols have been read,
*************** void init_minimal_symbol_collection (voi
*** 69,75 ****
  
  struct cleanup *make_cleanup_discard_minimal_symbols (void);
  
! /* Record a new minimal symbol.  This is the "full" entry point;
     simpler convenience entry points are also provided below.
     
     This returns a new minimal symbol.  It is ok to modify the returned
--- 76,83 ----
  
  struct cleanup *make_cleanup_discard_minimal_symbols (void);
  
! /**
!    Record a new minimal symbol.  This is the "full" entry point;
     simpler convenience entry points are also provided below.
     
     This returns a new minimal symbol.  It is ok to modify the returned
*************** struct cleanup *make_cleanup_discard_min
*** 80,95 ****
     
     Arguments are:
  
!    NAME - the symbol's name
!    NAME_LEN - the length of the name
!    COPY_NAME - if true, the minsym code must make a copy of NAME.  If
     false, then NAME must be NUL-terminated, and must have a lifetime
     that is at least as long as OBJFILE's lifetime.
!    ADDRESS - the address of the symbol
!    MS_TYPE - the type of the symbol
!    SECTION - the symbol's section
     appropriate obj_section for the minimal symbol.  This can be NULL.
!    OBJFILE - the objfile associated with the minimal symbol.  */
  
  struct minimal_symbol *prim_record_minimal_symbol_full
      (const char *name,
--- 88,103 ----
     
     Arguments are:
  
!    @param NAME - the symbol's name
!    @param NAME_LEN - the length of the name
!    @param COPY_NAME - if true, the minsym code must make a copy of NAME.  If
     false, then NAME must be NUL-terminated, and must have a lifetime
     that is at least as long as OBJFILE's lifetime.
!    @param ADDRESS - the address of the symbol
!    @param MS_TYPE - the type of the symbol
!    @param SECTION - the symbol's section
     appropriate obj_section for the minimal symbol.  This can be NULL.
!    @param OBJFILE - the objfile associated with the minimal symbol.  */
  
  struct minimal_symbol *prim_record_minimal_symbol_full
      (const char *name,
*************** struct minimal_symbol *prim_record_minim
*** 100,106 ****
       int section,
       struct objfile *objfile);
  
! /* Like prim_record_minimal_symbol_full, but:
     - uses strlen to compute NAME_LEN,
     - passes COPY_NAME = 0,
     - and passes a default SECTION, depending on the type
--- 108,115 ----
       int section,
       struct objfile *objfile);
  
! /**
!    Like prim_record_minimal_symbol_full, but:
     - uses strlen to compute NAME_LEN,
     - passes COPY_NAME = 0,
     - and passes a default SECTION, depending on the type
*************** void prim_record_minimal_symbol (const c
*** 111,117 ****
  				 enum minimal_symbol_type,
  				 struct objfile *);
  
! /* Like prim_record_minimal_symbol_full, but:
     - uses strlen to compute NAME_LEN,
     - passes COPY_NAME = 0.  */
  
--- 120,127 ----
  				 enum minimal_symbol_type,
  				 struct objfile *);
  
! /**
!    Like prim_record_minimal_symbol_full, but:
     - uses strlen to compute NAME_LEN,
     - passes COPY_NAME = 0.  */
  
*************** struct minimal_symbol *prim_record_minim
*** 122,142 ****
       int section,
       struct objfile *);
  
! /* Install the minimal symbols that have been collected into the given
     objfile.  After this is called, the cleanup returned by
     make_cleanup_discard_minimal_symbols should be run in order to
!    clean up global state.  */
  
! void install_minimal_symbols (struct objfile *);
  
! /* Create the terminating entry of OBJFILE's minimal symbol table.
     If OBJFILE->msymbols is zero, allocate a single entry from
     OBJFILE->objfile_obstack; otherwise, just initialize
     OBJFILE->msymbols[OBJFILE->minimal_symbol_count].  */
  
  void terminate_minimal_symbol_table (struct objfile *objfile);
  
! /* Sort all the minimal symbols in OBJFILE.  This should be only be
     called after relocating symbols; it ensures that the minimal
     symbols are properly sorted by address.  */
  
--- 132,156 ----
       int section,
       struct objfile *);
  
! /**
!    Install the minimal symbols that have been collected into the given
     objfile.  After this is called, the cleanup returned by
     make_cleanup_discard_minimal_symbols should be run in order to
!    clean up global state.
!    @param objfile the objfile from which to get minimal symbols  */
  
! void install_minimal_symbols (struct objfile *objfile);
  
! /**
!    Create the terminating entry of OBJFILE's minimal symbol table.
     If OBJFILE->msymbols is zero, allocate a single entry from
     OBJFILE->objfile_obstack; otherwise, just initialize
     OBJFILE->msymbols[OBJFILE->minimal_symbol_count].  */
  
  void terminate_minimal_symbol_table (struct objfile *objfile);
  
! /**
!    Sort all the minimal symbols in OBJFILE.  This should be only be
     called after relocating symbols; it ensures that the minimal
     symbols are properly sorted by address.  */
  
*************** void msymbols_sort (struct objfile *objf
*** 144,159 ****
  
  \f
  
! /* Compute a hash code for the string argument.  */
  
  unsigned int msymbol_hash (const char *);
  
! /* Like msymbol_hash, but compute a hash code that is compatible with
     strcmp_iw.  */
  
  unsigned int msymbol_hash_iw (const char *);
  
! /* Compute the next hash value from previous HASH and the character C.  This
     is only a GDB in-memory computed value with no external files compatibility
     requirements.  */
  
--- 158,175 ----
  
  \f
  
! /** Compute a hash code for the string argument.  */
  
  unsigned int msymbol_hash (const char *);
  
! /**
!    Like msymbol_hash, but compute a hash code that is compatible with
     strcmp_iw.  */
  
  unsigned int msymbol_hash_iw (const char *);
  
! /**
!    Compute the next hash value from previous HASH and the character C.  This
     is only a GDB in-memory computed value with no external files compatibility
     requirements.  */
  
*************** unsigned int msymbol_hash_iw (const char
*** 162,199 ****
  
  \f
  
! /* Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME.  If OBJF is non-NULL, limit
     the search to that objfile.  If SFILE is non-NULL, the only file-scope
     symbols considered will be from that source file (global symbols are
     still preferred).  Returns a pointer to the minimal symbol that
!    matches, or NULL if no match is found.  */
  
! struct minimal_symbol *lookup_minimal_symbol (const char *,
! 					      const char *,
! 					      struct objfile *);
  
! /* Like lookup_minimal_symbol, but searches all files and objfiles
!    and returns a bound minimal symbol.  */
! 
! struct bound_minimal_symbol lookup_bound_minimal_symbol (const char *);
! 
! /* Find the minimal symbol named NAME, and return both the minsym
!    struct and its objfile.  This only checks the linkage name.  */
! 
! struct bound_minimal_symbol lookup_minimal_symbol_and_objfile (const char *);
! 
! /* Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME and has text type.  If OBJF
     is non-NULL, limit the search to that objfile.  Returns a pointer
     to the minimal symbol that matches, or NULL if no match is found.
  
     This function only searches the mangled (linkage) names.  */
  
! struct minimal_symbol *lookup_minimal_symbol_text (const char *,
! 						   struct objfile *);
  
! /* Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME and is a solib trampoline.
     If OBJF is non-NULL, limit the search to that objfile.  Returns a
     pointer to the minimal symbol that matches, or NULL if no match is
--- 178,229 ----
  
  \f
  
! /**
!    Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME.  If OBJF is non-NULL, limit
     the search to that objfile.  If SFILE is non-NULL, the only file-scope
     symbols considered will be from that source file (global symbols are
     still preferred).  Returns a pointer to the minimal symbol that
!    matches, or NULL if no match is found.
!    @param name string to look for
!    @param sfile if supplied, name of a source file
!    @param objf if supplied, pointer to objfile to lookup in
!   */
! 
! struct minimal_symbol *lookup_minimal_symbol (const char *name,
! 					      const char *sfile,
! 					      struct objfile *objf);
! 
! /**
!    Like lookup_minimal_symbol, but searches all files and objfiles
!    and returns a bound minimal symbol.
!    @param name string to look for
!    @return minimal symbol and its objfile  */
! 
! struct bound_minimal_symbol lookup_bound_minimal_symbol (const char *name);
! 
! /**
!    Find the minimal symbol named NAME, and return both the minsym
!    struct and its objfile.  This only checks the linkage name.
!    @param name string to look for
!    @return minimal symbol and its objfile  */
  
! struct bound_minimal_symbol lookup_minimal_symbol_and_objfile
!     (const char *name);
  
! /**
!    Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME and has text type.  If OBJF
     is non-NULL, limit the search to that objfile.  Returns a pointer
     to the minimal symbol that matches, or NULL if no match is found.
  
     This function only searches the mangled (linkage) names.  */
  
! struct minimal_symbol *lookup_minimal_symbol_text (const char *name,
! 						   struct objfile *objf);
  
! /**
!    Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME and is a solib trampoline.
     If OBJF is non-NULL, limit the search to that objfile.  Returns a
     pointer to the minimal symbol that matches, or NULL if no match is
*************** struct minimal_symbol *lookup_minimal_sy
*** 205,211 ****
      (const char *,
       struct objfile *);
  
! /* Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME and PC.  If OBJF is non-NULL,
     limit the search to that objfile.  Returns a pointer to the minimal
     symbol that matches, or NULL if no match is found.  */
--- 235,242 ----
      (const char *,
       struct objfile *);
  
! /**
!    Look through all the current minimal symbol tables and find the
     first minimal symbol that matches NAME and PC.  If OBJF is non-NULL,
     limit the search to that objfile.  Returns a pointer to the minimal
     symbol that matches, or NULL if no match is found.  */
*************** struct minimal_symbol *lookup_minimal_sy
*** 213,219 ****
  struct minimal_symbol *lookup_minimal_symbol_by_pc_name
      (CORE_ADDR, const char *, struct objfile *);
  
! /* Search through the minimal symbol table for each objfile and find
     the symbol whose address is the largest address that is still less
     than or equal to PC, and which matches SECTION.
  
--- 244,251 ----
  struct minimal_symbol *lookup_minimal_symbol_by_pc_name
      (CORE_ADDR, const char *, struct objfile *);
  
! /**
!    Search through the minimal symbol table for each objfile and find
     the symbol whose address is the largest address that is still less
     than or equal to PC, and which matches SECTION.
  
*************** struct bound_minimal_symbol lookup_minim
*** 227,233 ****
      (CORE_ADDR,
       struct obj_section *);
  
! /* Backward compatibility: search through the minimal symbol table 
     for a matching PC (no section given).
     
     This is a wrapper that calls lookup_minimal_symbol_by_pc_section
--- 259,266 ----
      (CORE_ADDR,
       struct obj_section *);
  
! /**
!    Backward compatibility: search through the minimal symbol table 
     for a matching PC (no section given).
     
     This is a wrapper that calls lookup_minimal_symbol_by_pc_section
*************** struct bound_minimal_symbol lookup_minim
*** 235,241 ****
  
  struct bound_minimal_symbol lookup_minimal_symbol_by_pc (CORE_ADDR);
  
! /* Iterate over all the minimal symbols in the objfile OBJF which
     match NAME.  Both the ordinary and demangled names of each symbol
     are considered.  The caller is responsible for canonicalizing NAME,
     should that need to be done.
--- 268,275 ----
  
  struct bound_minimal_symbol lookup_minimal_symbol_by_pc (CORE_ADDR);
  
! /**
!    Iterate over all the minimal symbols in the objfile OBJF which
     match NAME.  Both the ordinary and demangled names of each symbol
     are considered.  The caller is responsible for canonicalizing NAME,
     should that need to be done.
Index: utils.c
===================================================================
RCS file: /cvs/src/src/gdb/utils.c,v
retrieving revision 1.309
diff -p -r1.309 utils.c
*** utils.c	11 Oct 2013 08:23:10 -0000	1.309
--- utils.c	11 Oct 2013 21:19:32 -0000
*************** vwarning (const char *string, va_list ar
*** 561,572 ****
      }
  }
  
- /* Print a warning message.
-    The first argument STRING is the warning message, used as a fprintf string,
-    and the remaining args are passed as arguments to it.
-    The primary difference between warnings and errors is that a warning
-    does not force the return to command level.  */
- 
  void
  warning (const char *string, ...)
  {
--- 561,566 ----
*************** host_char_to_target (struct gdbarch *gdb
*** 1425,1445 ****
    return result;
  }
  
- /* Parse a C escape sequence.  STRING_PTR points to a variable
-    containing a pointer to the string to parse.  That pointer
-    should point to the character after the \.  That pointer
-    is updated past the characters we use.  The value of the
-    escape sequence is returned.
- 
-    A negative value means the sequence \ newline was seen,
-    which is supposed to be equivalent to nothing at all.
- 
-    If \ is followed by a null character, we return a negative
-    value and leave the string pointer pointing at the null character.
- 
-    If \ is followed by 000, we return 0 and leave the string pointer
-    after the zeros.  A value of 0 does not mean end of string.  */
- 
  int
  parse_escape (struct gdbarch *gdbarch, const char **string_ptr)
  {
--- 1419,1424 ----
*************** wrap_here (char *indent)
*** 1953,1965 ****
      }
  }
  
- /* Print input string to gdb_stdout, filtered, with wrap, 
-    arranging strings in columns of n chars.  String can be
-    right or left justified in the column.  Never prints 
-    trailing spaces.  String should never be longer than
-    width.  FIXME: this could be useful for the EXAMINE 
-    command, which currently doesn't tabulate very well.  */
- 
  void
  puts_filtered_tabular (char *string, int width, int right)
  {
--- 1932,1937 ----
*************** strcmp_iw (const char *string1, const ch
*** 2526,2568 ****
    return (*string1 != '\0' && *string1 != '(') || (*string2 != '\0');
  }
  
- /* This is like strcmp except that it ignores whitespace and treats
-    '(' as the first non-NULL character in terms of ordering.  Like
-    strcmp (and unlike strcmp_iw), it returns negative if STRING1 <
-    STRING2, 0 if STRING2 = STRING2, and positive if STRING1 > STRING2
-    according to that ordering.
- 
-    If a list is sorted according to this function and if you want to
-    find names in the list that match some fixed NAME according to
-    strcmp_iw(LIST_ELT, NAME), then the place to start looking is right
-    where this function would put NAME.
- 
-    This function must be neutral to the CASE_SENSITIVITY setting as the user
-    may choose it during later lookup.  Therefore this function always sorts
-    primarily case-insensitively and secondarily case-sensitively.
- 
-    Here are some examples of why using strcmp to sort is a bad idea:
- 
-    Whitespace example:
- 
-    Say your partial symtab contains: "foo<char *>", "goo".  Then, if
-    we try to do a search for "foo<char*>", strcmp will locate this
-    after "foo<char *>" and before "goo".  Then lookup_partial_symbol
-    will start looking at strings beginning with "goo", and will never
-    see the correct match of "foo<char *>".
- 
-    Parenthesis example:
- 
-    In practice, this is less like to be an issue, but I'll give it a
-    shot.  Let's assume that '$' is a legitimate character to occur in
-    symbols.  (Which may well even be the case on some systems.)  Then
-    say that the partial symbol table contains "foo$" and "foo(int)".
-    strcmp will put them in this order, since '$' < '('.  Now, if the
-    user searches for "foo", then strcmp will sort "foo" before "foo$".
-    Then lookup_partial_symbol will notice that strcmp_iw("foo$",
-    "foo") is false, so it won't proceed to the actual match of
-    "foo(int)" with "foo".  */
- 
  int
  strcmp_iw_ordered (const char *string1, const char *string2)
  {
--- 2498,2503 ----
*************** strcmp_iw_ordered (const char *string1, 
*** 2641,2648 ****
      }
  }
  
- /* A simple comparison function with opposite semantics to strcmp.  */
- 
  int
  streq (const char *lhs, const char *rhs)
  {
--- 2576,2581 ----
*************** streq (const char *lhs, const char *rhs)
*** 2650,2661 ****
  }
  \f
  
- /*
-    ** subset_compare()
-    **    Answer whether string_to_compare is a full or partial match to
-    **    template_string.  The partial match must be in sequence starting
-    **    at index 0.
-  */
  int
  subset_compare (char *string_to_compare, char *template_string)
  {
--- 2583,2588 ----
*************** hex_string_custom: insufficient space to
*** 3031,3043 ****
    return result_end - width - 2;
  }
  
- /* Convert VAL to a numeral in the given radix.  For
-  * radix 10, IS_SIGNED may be true, indicating a signed quantity;
-  * otherwise VAL is interpreted as unsigned.  If WIDTH is supplied, 
-  * it is the minimum width (0-padded if needed).  USE_C_FORMAT means
-  * to use C format in all cases.  If it is false, then 'x' 
-  * and 'o' formats do not include a prefix (0x or leading 0).  */
- 
  char *
  int_string (LONGEST val, int radix, int is_signed, int width, 
  	    int use_c_format)
--- 2958,2963 ----
*************** int_string (LONGEST val, int radix, int 
*** 3078,3084 ****
      }
  }	
  
- /* Convert a CORE_ADDR into a string.  */
  const char *
  core_addr_to_string (const CORE_ADDR addr)
  {
--- 2998,3003 ----
*************** digit_to_int (unsigned char c)
*** 3318,3325 ****
      return tolower (c) - 'a' + 10;
  }
  
- /* As for strtoul, but for ULONGEST results.  */
- 
  ULONGEST
  strtoulst (const char *num, const char **trailer, int base)
  {
--- 3237,3242 ----
*************** ldirname (const char *filename)
*** 3417,3427 ****
    return dirname;
  }
  
- /* Call libiberty's buildargv, and return the result.
-    If buildargv fails due to out-of-memory, call nomem.
-    Therefore, the returned value is guaranteed to be non-NULL,
-    unless the parameter itself is NULL.  */
- 
  char **
  gdb_buildargv (const char *s)
  {
--- 3334,3339 ----
*************** gdb_buildargv (const char *s)
*** 3432,3437 ****
--- 3344,3351 ----
    return argv;
  }
  
+ /* See utils.h.  */
+ 
  int
  compare_positive_ints (const void *ap, const void *bp)
  {
*************** compare_positive_ints (const void *ap, c
*** 3440,3446 ****
    return * (int *) ap - * (int *) bp;
  }
  
! /* String compare function for qsort.  */
  
  int
  compare_strings (const void *arg1, const void *arg2)
--- 3354,3360 ----
    return * (int *) ap - * (int *) bp;
  }
  
! /* See utils.h.  */
  
  int
  compare_strings (const void *arg1, const void *arg2)
*************** gdb_bfd_errmsg (bfd_error_type error_tag
*** 3492,3498 ****
    return ret;
  }
  
! /* Return ARGS parsed as a valid pid, or throw an error.  */
  
  int
  parse_pid_to_attach (char *args)
--- 3406,3412 ----
    return ret;
  }
  
! /* See utils.h.  */
  
  int
  parse_pid_to_attach (char *args)
*************** make_bpstat_clear_actions_cleanup (void)
*** 3529,3537 ****
    return make_cleanup (do_bpstat_clear_actions_cleanup, NULL);
  }
  
! /* Check for GCC >= 4.x according to the symtab->producer string.  Return minor
!    version (x) of 4.x in such case.  If it is not GCC or it is GCC older than
!    4.x return -1.  If it is GCC 5.x or higher return INT_MAX.  */
  
  int
  producer_is_gcc_ge_4 (const char *producer)
--- 3443,3449 ----
    return make_cleanup (do_bpstat_clear_actions_cleanup, NULL);
  }
  
! /* See utils.h.  */
  
  int
  producer_is_gcc_ge_4 (const char *producer)
Index: utils.h
===================================================================
RCS file: /cvs/src/src/gdb/utils.h,v
retrieving revision 1.13
diff -p -r1.13 utils.h
*** utils.h	11 Oct 2013 08:23:10 -0000	1.13
--- utils.h	11 Oct 2013 21:19:32 -0000
*************** extern void initialize_utils (void);
*** 30,56 ****
  
  extern int sevenbit_strings;
  
! extern char *savestring (const char *, size_t);
  
  extern int strcmp_iw (const char *, const char *);
  
! extern int strcmp_iw_ordered (const char *, const char *);
  
! extern int streq (const char *, const char *);
  
! extern int subset_compare (char *, char *);
  
  ULONGEST strtoulst (const char *num, const char **trailer, int base);
  
  int compare_positive_ints (const void *ap, const void *bp);
  int compare_strings (const void *ap, const void *bp);
  
! /* This is defined in *-hdep.c, e.g., posix-hdep.c.  */
  extern char *safe_strerror (int);
  
! /* A wrapper for bfd_errmsg to produce a more helpful error message
     in the case of bfd_error_file_ambiguously recognized.
!    MATCHING, if non-NULL, is the corresponding argument to
     bfd_check_format_matches, and will be freed.  */
  
  extern const char *gdb_bfd_errmsg (bfd_error_type error_tag, char **matching);
--- 30,123 ----
  
  extern int sevenbit_strings;
  
! /**
!    Make a copy of a string, using freshly-allocated space and limiting
!    to the given length.  Space is gotten using xmalloc.
! 
!    @param ptr pointer to the string to be copied
!    @param len maximum length to copy.  If the original string is longer,
!    then the copy will be truncated to len bytes.  */
! 
! extern char *savestring (const char *ptr, size_t len);
  
  extern int strcmp_iw (const char *, const char *);
  
! /**
!    This is like strcmp except that it ignores whitespace and treats
!    '(' as the first non-NULL character in terms of ordering.  Like
!    strcmp (and unlike strcmp_iw), it returns negative if STRING1 <
!    STRING2, 0 if STRING2 = STRING2, and positive if STRING1 > STRING2
!    according to that ordering.
! 
!    If a list is sorted according to this function and if you want to
!    find names in the list that match some fixed NAME according to
!    strcmp_iw(LIST_ELT, NAME), then the place to start looking is right
!    where this function would put NAME.
! 
!    This function must be neutral to the CASE_SENSITIVITY setting as the user
!    may choose it during later lookup.  Therefore this function always sorts
!    primarily case-insensitively and secondarily case-sensitively.
! 
!    Here are some examples of why using strcmp to sort is a bad idea:
! 
!    Whitespace example:
! 
!    Say your partial symtab contains: "foo<char *>", "goo".  Then, if
!    we try to do a search for "foo<char*>", strcmp will locate this
!    after "foo<char *>" and before "goo".  Then lookup_partial_symbol
!    will start looking at strings beginning with "goo", and will never
!    see the correct match of "foo<char *>".
! 
!    Parenthesis example:
! 
!    In practice, this is less like to be an issue, but I'll give it a
!    shot.  Let's assume that '$' is a legitimate character to occur in
!    symbols.  (Which may well even be the case on some systems.)  Then
!    say that the partial symbol table contains "foo$" and "foo(int)".
!    strcmp will put them in this order, since '$' < '('.  Now, if the
!    user searches for "foo", then strcmp will sort "foo" before "foo$".
!    Then lookup_partial_symbol will notice that strcmp_iw("foo$",
!    "foo") is false, so it won't proceed to the actual match of
!    "foo(int)" with "foo".  */
! 
! extern int strcmp_iw_ordered (const char *string1, const char *string2);
! 
! /** A simple comparison function with opposite semantics to strcmp.  */
! 
! extern int streq (const char *lhs, const char *rhs);
! 
! /**
!    Answer whether string_to_compare is a full or partial match to
!    template_string.  The partial match must be in sequence starting
!    at index 0.  */
  
! extern int subset_compare (char *string_to_compare, char *template_string);
  
! /** As for strtoul, but for ULONGEST results.  */
  
  ULONGEST strtoulst (const char *num, const char **trailer, int base);
  
+ /** Integer compare function suitable for qsort.  */
+ 
  int compare_positive_ints (const void *ap, const void *bp);
+ 
+ /** String compare function suitable for qsort.  */
+ 
  int compare_strings (const void *ap, const void *bp);
  
! /**
!    A host-specific version of strerror.
! 
!    This is defined in *-hdep.c, e.g., posix-hdep.c.  */
! 
  extern char *safe_strerror (int);
  
! /**
!    A wrapper for bfd_errmsg to produce a more helpful error message
     in the case of bfd_error_file_ambiguously recognized.
! 
!    @param error_tag
!    @param matching if non-NULL, is the corresponding argument to
     bfd_check_format_matches, and will be freed.  */
  
  extern const char *gdb_bfd_errmsg (bfd_error_type error_tag, char **matching);
*************** struct timeval get_prompt_for_continue_w
*** 62,72 ****
  \f
  /* Parsing utilites.  */
  
  extern int parse_pid_to_attach (char *args);
  
  extern int parse_escape (struct gdbarch *, const char **);
  
! char **gdb_buildargv (const char *);
  \f
  /* Cleanup utilities.  */
  
--- 129,163 ----
  \f
  /* Parsing utilites.  */
  
+ /** Return ARGS parsed as a valid pid, or throw an error.  */
+ 
  extern int parse_pid_to_attach (char *args);
  
+ /**
+    Parse a C escape sequence.  STRING_PTR points to a variable
+    containing a pointer to the string to parse.  That pointer
+    should point to the character after the \.  That pointer
+    is updated past the characters we use.  The value of the
+    escape sequence is returned.
+ 
+    A negative value means the sequence \ newline was seen,
+    which is supposed to be equivalent to nothing at all.
+ 
+    If \ is followed by a null character, we return a negative
+    value and leave the string pointer pointing at the null character.
+ 
+    If \ is followed by 000, we return 0 and leave the string pointer
+    after the zeros.  A value of 0 does not mean end of string.  */
+ 
  extern int parse_escape (struct gdbarch *, const char **);
  
! /**
!    Call libiberty's buildargv, and return the result.
!    If buildargv fails due to out-of-memory, call nomem.
!    Therefore, the returned value is guaranteed to be non-NULL,
!    unless the parameter itself is NULL.  */
! 
! char **gdb_buildargv (const char *s);
  \f
  /* Cleanup utilities.  */
  
*************** extern struct cleanup *make_bpstat_clear
*** 126,132 ****
  \f
  /* Path utilities.  */
  
! extern char *gdb_realpath (const char *);
  
  extern int gdb_filename_fnmatch (const char *pattern, const char *string,
  				 int flags);
--- 217,229 ----
  \f
  /* Path utilities.  */
  
! /**
!    Get the canonicalized absolute pathname for the given filename,
!    returning the result in freshly-allocated memory.  This is basically
!    just a host-independent wrapper for realpath().
!    @param filename the filename to get a path for  */
! 
! extern char *gdb_realpath (const char *filename);
  
  extern int gdb_filename_fnmatch (const char *pattern, const char *string,
  				 int flags);
*************** extern void reinitialize_more_filter (vo
*** 153,170 ****
  extern int pagination_enabled;
  
  /* Global ui_file streams.  These are all defined in main.c.  */
! /* Normal results */
  extern struct ui_file *gdb_stdout;
! /* Input stream */
  extern struct ui_file *gdb_stdin;
! /* Serious error notifications */
  extern struct ui_file *gdb_stderr;
! /* Log/debug/trace messages that should bypass normal stdout/stderr
     filtering.  For moment, always call this stream using
     *_unfiltered.  In the very near future that restriction shall be
     removed - either call shall be unfiltered.  (cagney 1999-06-13).  */
  extern struct ui_file *gdb_stdlog;
! /* Target output that should bypass normal stdout/stderr filtering.
     For moment, always call this stream using *_unfiltered.  In the
     very near future that restriction shall be removed - either call
     shall be unfiltered.  (cagney 1999-07-02).  */
--- 250,270 ----
  extern int pagination_enabled;
  
  /* Global ui_file streams.  These are all defined in main.c.  */
! 
! /** ui_file stream for normal results */
  extern struct ui_file *gdb_stdout;
! /** ui_file stream for input */
  extern struct ui_file *gdb_stdin;
! /** ui_file stream for serious error notifications */
  extern struct ui_file *gdb_stderr;
! /**
!    Log/debug/trace messages that should bypass normal stdout/stderr
     filtering.  For moment, always call this stream using
     *_unfiltered.  In the very near future that restriction shall be
     removed - either call shall be unfiltered.  (cagney 1999-06-13).  */
  extern struct ui_file *gdb_stdlog;
! /**
!    Target output that should bypass normal stdout/stderr filtering.
     For moment, always call this stream using *_unfiltered.  In the
     very near future that restriction shall be removed - either call
     shall be unfiltered.  (cagney 1999-07-02).  */
*************** extern struct ui_file *gdb_stdtargin;
*** 175,198 ****
--- 275,325 ----
  /* More generic printf like operations.  Filtered versions may return
     non-locally on error.  */
  
+ /** Write a string to output, controlled by pagination.  */
+ 
  extern void fputs_filtered (const char *, struct ui_file *);
  
+ /** Write a string to output, with no filter.  */
+ 
  extern void fputs_unfiltered (const char *, struct ui_file *);
  
+ /** Write a single char to output.  */
+ 
  extern int fputc_filtered (int c, struct ui_file *);
  
+ /** Write a single char to output, unfiltered.  */
+ 
  extern int fputc_unfiltered (int c, struct ui_file *);
  
+ /** Write a single char to gdb_stdout, filtered.  */
+ 
  extern int putchar_filtered (int c);
  
+ /** Write a single char to gdb_stdout, unfiltered.  */
+ 
  extern int putchar_unfiltered (int c);
  
+ /** Write a string to gdb_stdout, filtered.  */
+ 
  extern void puts_filtered (const char *);
  
+ /** Write a string to gdb_stdout, unfiltered.  */
+ 
  extern void puts_unfiltered (const char *);
  
+ /**
+    Print input string to gdb_stdout, filtered, with wrap, 
+    arranging strings in columns of n chars.  String can be
+    right or left justified in the column.  Never prints 
+    trailing spaces.  String should never be longer than
+    width.  */
+ 
  extern void puts_filtered_tabular (char *string, int width, int right);
  
+ /**
+    Put out the given string, with special characters escaped, and
+    enclosed by the given prefix and suffix strings.  */
+ 
  extern void puts_debug (char *prefix, char *string, char *suffix);
  
  extern void vprintf_filtered (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
*************** extern void fputstrn_filtered (const cha
*** 238,253 ****
  extern void fputstrn_unfiltered (const char *str, int n, int quotr,
  				 struct ui_file * stream);
  
! /* Display the host ADDR on STREAM formatted as ``0x%x''.  */
  extern void gdb_print_host_address (const void *addr, struct ui_file *stream);
  
  extern const char *host_address_to_string (const void *addr);
  
! /* Convert CORE_ADDR to string in platform-specific manner.
     This is usually formatted similar to 0x%lx.  */
  extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
  
! /* Return a string representation in hexadecimal notation of ADDRESS,
     which is suitable for printing.  */
  
  extern const char *print_core_address (struct gdbarch *gdbarch,
--- 365,383 ----
  extern void fputstrn_unfiltered (const char *str, int n, int quotr,
  				 struct ui_file * stream);
  
! /** Display the host ADDR on STREAM formatted as ``0x%x''.  */
  extern void gdb_print_host_address (const void *addr, struct ui_file *stream);
  
  extern const char *host_address_to_string (const void *addr);
  
! /**
!    Convert CORE_ADDR to string in platform-specific manner.
     This is usually formatted similar to 0x%lx.  */
+ 
  extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
  
! /**
!    Return a string representation in hexadecimal notation of ADDRESS,
     which is suitable for printing.  */
  
  extern const char *print_core_address (struct gdbarch *gdbarch,
*************** extern const char *print_core_address (s
*** 257,281 ****
  extern hashval_t core_addr_hash (const void *ap);
  extern int core_addr_eq (const void *ap, const void *bp);
  
! /* %d for LONGEST */
  extern char *plongest (LONGEST l);
! /* %u for ULONGEST */
  extern char *pulongest (ULONGEST l);
  
  extern char *phex (ULONGEST l, int sizeof_l);
  extern char *phex_nz (ULONGEST l, int sizeof_l);
- extern char *int_string (LONGEST, int, int, int, int);
  
! /* Convert a CORE_ADDR into a HEX string with leading zeros.
     The output from core_addr_to_string() can be passed direct to
     string_to_core_addr().  */
  extern const char *core_addr_to_string (const CORE_ADDR addr);
  extern const char *core_addr_to_string_nz (const CORE_ADDR addr);
  extern CORE_ADDR string_to_core_addr (const char *my_string);
  
! /* Return a string that contains a number formatted as a hex
     string.  */
  extern char *hex_string (LONGEST);
  extern char *hex_string_custom (LONGEST, int);
  
  extern void fprintf_symbol_filtered (struct ui_file *, const char *,
--- 387,466 ----
  extern hashval_t core_addr_hash (const void *ap);
  extern int core_addr_eq (const void *ap, const void *bp);
  
! /**
!    Print a LONGEST in %d format.
!    @param l the (signed) integer to print
!    @return a string of decimal digits  */
! 
  extern char *plongest (LONGEST l);
! 
! /**
!    Print a ULONGEST in %u format.
!    @param l the (unsigned) integer to print
!    @return a string of decimal digits  */
! 
  extern char *pulongest (ULONGEST l);
  
+ /**
+    Print a ULONGEST in %0x format (hex with leading zeros).
+    @param l the unsigned integer to print
+    @param sizeof_l size of integer to print; values of 2, 4, and 8
+    force sizes of the respective numbers of bytes, any other value
+    will use sizeof(l)
+    @return a string of hexadecimal digits, from static allocation  */
+ 
  extern char *phex (ULONGEST l, int sizeof_l);
+ 
+ /**
+    Print a ULONGEST in %x format (hex, and NO leading zeros).
+    @param l the unsigned integer to print
+    @param sizeof_l size of integer to print; values of 2, 4, and 8
+    force sizes of the respective numbers of bytes, any other value
+    will use sizeof(l)
+    @return a string of hexadecimal digits, from static allocation  */
+ 
  extern char *phex_nz (ULONGEST l, int sizeof_l);
  
! /**
!    Convert VAL to a numeral in the given radix.  For
!    radix 10, IS_SIGNED may be true, indicating a signed quantity;
!    otherwise VAL is interpreted as unsigned.  If WIDTH is supplied, 
!    it is the minimum width (0-padded if needed).  USE_C_FORMAT means
!    to use C format in all cases.  If it is false, then 'x' 
!    and 'o' formats do not include a prefix (0x or leading 0).  */
! 
! extern char *int_string (LONGEST val, int radix, int is_signed, int width, 
! 			 int use_c_format);
! 
! /**
!    Convert a CORE_ADDR into a hex string with leading zeros,
!    and prefixed with "0x" as in C syntax.
     The output from core_addr_to_string() can be passed direct to
     string_to_core_addr().  */
+ 
  extern const char *core_addr_to_string (const CORE_ADDR addr);
+ 
+ /**
+    Convert a CORE_ADDR into a hex string, withOUT leading zeros,
+    and prefixed with "0x" as in C syntax.
+    The output from core_addr_to_string() can be passed direct to
+    string_to_core_addr().  */
+ 
  extern const char *core_addr_to_string_nz (const CORE_ADDR addr);
+ 
+ /**
+    Parse a decimal or hexadecimal string of digits, and return
+    a CORE_ADDR.  A hexadecimal string must begin with a "0x";
+    any invalid digits result in an error().  */
+ 
  extern CORE_ADDR string_to_core_addr (const char *my_string);
  
! /**
!    Return a string that contains a number formatted as a hex
     string.  */
+ 
  extern char *hex_string (LONGEST);
+ 
  extern char *hex_string_custom (LONGEST, int);
  
  extern void fprintf_symbol_filtered (struct ui_file *, const char *,
*************** extern void print_sys_errmsg (const char
*** 293,299 ****
  
  extern void (*deprecated_error_begin_hook) (void);
  
! /* Message to be printed before the warning message, when a warning occurs.  */
  
  extern char *warning_pre_print;
  
--- 478,486 ----
  
  extern void (*deprecated_error_begin_hook) (void);
  
! /**
!    String to be printed before the warning message, when a warning
!    occurs.  (Typically something like "warning:".)  */
  
  extern char *warning_pre_print;
  
*************** extern void internal_vwarning (const cha
*** 322,329 ****
--- 509,526 ----
  extern void internal_warning (const char *file, int line,
  			      const char *, ...) ATTRIBUTE_PRINTF (3, 4);
  
+ /**
+    Print a warning message.
+ 
+    The first argument STRING is the warning message, used as a fprintf string,
+    and the remaining args are passed as arguments to it.
+    The primary difference between warnings and errors is that a warning
+    does not force the return to command level.  */
+ 
  extern void warning (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
  
+ /** Like warning, but takes a va_list of arguments.  */
+ 
  extern void vwarning (const char *, va_list args) ATTRIBUTE_PRINTF (1, 0);
  \f
  /* Misc. utilities.  */
*************** void dummy_obstack_deallocate (void *obj
*** 337,342 ****
--- 534,545 ----
  extern pid_t wait_to_die_with_timeout (pid_t pid, int *status, int timeout);
  #endif
  
+ /**
+    Check for GCC >= 4.x according to the symtab->producer string.
+    Return minor version (x) of 4.x in such case.  If it is not GCC or
+    it is GCC older than 4.x return -1.  If it is GCC 5.x or higher
+    return INT_MAX.  */
+ 
  extern int producer_is_gcc_ge_4 (const char *producer);
  
  extern int myread (int, char *, int);
Index: doc/Doxyfile-base
===================================================================
RCS file: doc/Doxyfile-base
diff -N doc/Doxyfile-base
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/Doxyfile-base	11 Oct 2013 21:19:32 -0000
***************
*** 0 ****
--- 1,59 ----
+ # Base doxyfile for GDB.
+ 
+ # The definitions in this file are shared by several different
+ # renditions of GDB documentation, and should reflect common
+ # GDB practices and assumptions.
+ 
+ # Note that this file is always included directly, does not
+ # get processed through configury.
+ 
+ PROJECT_NAME = "GDB"
+ 
+ # Start out with an everything-is-documented assumption.  (Later
+ # on we may want to limit to only specific areas.)
+ 
+ EXTRACT_ALL = YES
+ 
+ # These are intended for GDB developers, so include anything flagged
+ # "internal".
+ 
+ INTERNAL_DOCS = YES
+ 
+ # Always dig through subdirectories.
+ 
+ RECURSIVE = YES
+ 
+ #INCLUDE_FILE_PATTERNS = *.h *.def
+ 
+ # We would like the .def files to be found.
+ #FILE_PATTERNS = *.c
+ 
+ # Comment this out (or set to YES) to see lots of finicky complaints.
+ WARN_IF_DOC_ERROR = NO
+ 
+ # By default, HTML will be generated.
+ 
+ # We are missing javascript to make this work?
+ #HTML_DYNAMIC_SECTIONS = YES
+ 
+ # In 1.8 only?
+ #HTML_INDEX_NUM_ENTRIES = 10
+ 
+ # We never have a use for a LaTex version of this.
+ 
+ GENERATE_LATEX = NO
+ 
+ # We always want to get to sources easily.
+ 
+ SOURCE_BROWSER = YES
+ 
+ # We would like to have full macro expansion, but it's very slow.
+ 
+ ENABLE_PREPROCESSING = YES
+ #MACRO_EXPANSION = YES
+ #EXPAND_ONLY_PREDEF = YES
+ #PREDEFINED = __attribute__(x)= __extension__=
+ 
+ # Suppress the huge volume of chatter.
+ 
+ QUIET = YES
Index: doc/Doxyfile-gdb-api.in
===================================================================
RCS file: doc/Doxyfile-gdb-api.in
diff -N doc/Doxyfile-gdb-api.in
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/Doxyfile-gdb-api.in	11 Oct 2013 21:19:32 -0000
***************
*** 0 ****
--- 1,35 ----
+ # Doxygen file for GDB API, aka symbols used everywhere in GDB.
+ 
+ @INCLUDE = @srcdir@/Doxyfile-base
+ 
+ PROJECT_NAME = "GDB (API)"
+ 
+ #PROJECT_NUMBER = "@PACKAGE_VERSION@"
+ 
+ INTERNAL_DOCS = YES
+ FORCE_LOCAL_INCLUDES = YES
+ 
+ INCLUDE_PATH = @srcdir@/../ @srcdir@/../common @srcdir@/../../include/
+ 
+ # Get the main sources, excluding auxiliary programs and anything
+ # that might be confusing.
+ 
+ INPUT = @srcdir@/../ \
+                  ../ \
+         @srcdir@/../../include/gdb/
+ 
+ #INPUT = @srcdir@/../gdbtypes.h
+ 
+ EXCLUDE = @srcdir@/../gdbserver/ \
+                    ../gdbserver/ \
+           @srcdir@/../gnulib/ \
+ 		   ../build-gnulib/ \
+           @srcdir@/../testsuite/ \
+ 		   ../testsuite/ \
+           @srcdir@/../stubs/
+ 
+ HTML_OUTPUT = ./doxy/gdb-api
+ 
+ # Suppress classes/structs local to source files.
+ 
+ EXTRACT_LOCAL_CLASSES = NO
Index: doc/Doxyfile-gdb-xref.in
===================================================================
RCS file: doc/Doxyfile-gdb-xref.in
diff -N doc/Doxyfile-gdb-xref.in
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/Doxyfile-gdb-xref.in	11 Oct 2013 21:19:32 -0000
***************
*** 0 ****
--- 1,42 ----
+ # Doxygen file for a full GDB cross-reference.
+ 
+ @INCLUDE = @srcdir@/Doxyfile-base
+ 
+ PROJECT_NAME = "GDB (xrefs)"
+ 
+ #PROJECT_NUMBER = "@PACKAGE_VERSION@"
+ 
+ INCLUDE_PATH = @srcdir@/../ @srcdir@/../common @srcdir@/../../include/
+ 
+ # Get the main sources, excluding auxiliary programs and anything
+ # that might be confusing.
+ 
+ INPUT = @srcdir@/../ ../
+ 
+ EXCLUDE = @srcdir@/../gdbserver/ \
+                    ../gdbserver/ \
+           @srcdir@/../gnulib/ \
+ 		   ../build-gnulib/ \
+           @srcdir@/../testsuite/ \
+ 		   ../testsuite/ \
+           @srcdir@/../stubs/
+ 
+ HTML_OUTPUT = ./doxy/gdb-xref
+ 
+ # We want to use the XML for analysis and statistics.
+ 
+ GENERATE_XML = YES
+ XML_OUTPUT = ./doxy/xml
+ 
+ # Include everything possible.
+ 
+ FORCE_LOCAL_INCLUDES = YES
+ EXTRACT_PRIVATE = YES
+ EXTRACT_STATIC = YES
+ 
+ # Build a full cross-reference.
+ 
+ REFERENCED_BY_RELATION = YES
+ REFERENCES_RELATION = YES
+ REFERENCES_LINK_SOURCE = NO
+ 
Index: doc/Doxyfile-gdbserver.in
===================================================================
RCS file: doc/Doxyfile-gdbserver.in
diff -N doc/Doxyfile-gdbserver.in
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- doc/Doxyfile-gdbserver.in	11 Oct 2013 21:19:32 -0000
***************
*** 0 ****
--- 1,28 ----
+ # Doxygen file for a GDBserver cross-reference.
+ 
+ @INCLUDE = @srcdir@/Doxyfile-base
+ 
+ PROJECT_NAME = "GDBserver"
+ 
+ #PROJECT_NUMBER = "@PACKAGE_VERSION@"
+ 
+ INCLUDE_PATH = @srcdir@/../common @srcdir@/../../include/
+ 
+ # Include just the directories that go into GDBserver.
+ 
+ INPUT = @srcdir@/../gdbserver @srcdir@/../common @srcdir@/../nat
+ 
+ # gdbreplay is its own program, avoid duplicate symbols.
+ 
+ EXCLUDE = @srcdir@/../gdbserver/gdbreplay.c
+ 
+ HTML_OUTPUT = ./doxy/gdbserver
+ 
+ # Build a full cross-reference.
+ 
+ REFERENCED_BY_RELATION = YES
+ REFERENCES_RELATION = YES
+ REFERENCES_LINK_SOURCE = NO
+ 
+ EXTRACT_PRIVATE = YES
+ EXTRACT_STATIC = YES
Index: doc/Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.65
diff -p -r1.65 Makefile.in
*** doc/Makefile.in	16 Sep 2013 18:00:34 -0000	1.65
--- doc/Makefile.in	11 Oct 2013 21:19:32 -0000
*************** ps: gdb.ps stabs.ps refcard.ps annotate.
*** 184,189 ****
--- 184,218 ----
  html: $(HTMLFILES)
  pdf: $(PDFFILES)
  man: $(MANS)
+ 
+ DOXYGEN = doxygen
+ doxyedit = sed -e 's,@srcdir\@,$(srcdir),g'
+ 
+ doxy:	doxy/gdb-api/index.html \
+ 	doxy/gdb-xref/index.html \
+ 	doxy/gdbserver/index.html
+ 
+ doxy/gdb-api/index.html: Doxyfile-gdb-api $(srcdir)/Doxyfile-base
+ 	-mkdir -p doxy
+ 	$(DOXYGEN) Doxyfile-gdb-api
+ 
+ doxy/gdb-xref/index.html: Doxyfile-gdb-xref $(srcdir)/Doxyfile-base
+ 	-mkdir -p doxy
+ 	$(DOXYGEN) Doxyfile-gdb-xref
+ 
+ doxy/gdbserver/index.html: Doxyfile-gdbserver $(srcdir)/Doxyfile-base
+ 	-mkdir -p doxy
+ 	$(DOXYGEN) Doxyfile-gdbserver
+ 
+ Doxyfile-gdb-api:	$(srcdir)/Doxyfile-gdb-api.in 
+ 	$(doxyedit) $(srcdir)/Doxyfile-gdb-api.in >Doxyfile-gdb-api
+ 
+ Doxyfile-gdb-xref:	$(srcdir)/Doxyfile-gdb-xref.in
+ 	$(doxyedit) $(srcdir)/Doxyfile-gdb-xref.in >Doxyfile-gdb-xref
+ 
+ Doxyfile-gdbserver:	$(srcdir)/Doxyfile-gdbserver.in
+ 	$(doxyedit) $(srcdir)/Doxyfile-gdbserver.in >Doxyfile-gdbserver
+ 
  all-doc: info dvi ps # pdf
  diststuff: info man
  	rm -f gdb-cfg.texi GDBvn.texi

Re: [RFC] Use Doxygen for internals documentation

[Yao Qi]

On 10/12/2013 06:13 AM, Stan Shebs wrote:
> This patch is the third and final step in the transition away from the
> old GDB internals manual.
>

I tried this patch, and overall, I like the doc generated by doxygen.

>
> To try it out, install doxygen, apply this patch to GDB, configure in
> the usual way, then do
>
> 	make doxy
>
> in the doc objdir.  This will produce a "doxy" subdir, with three
> subdirs in turn, each based on a different config file:
>
> 	doxy/gdb-api - GDB's "API", basically what is in .h files
> 	doxy/gdb-xref - the full xref, voluminous

Any reason to produce both of them?  I'd like to have a single one.

> 	doxy/gdbserver - GDBserver xref
> 	doxy/xml - XML version, for further script-crunching

Do you have an example that these xml files can be consumed by other tools?

>
> To see how the annotations work, look down through minsyms.h and
> utils.h, you can see the comments attached to declarations.
>

> types, see what is used and what is not used.
>
> So I think it's worth going ahead and introducing.  But of course
> something like this only works if everybody signs on, patches are
> required to have Doxygen annotations for header file additions, and
> so forth.  Look at the header file changes, try noodling around the
> Doxygen output, see if you're willing to be looking at all this for
> the next N years.
>

With this change, we need to write comments in a new way for doxygen.  I 
go through your patch to minsyms.h, and think the comment style looks
fine to me.

-- 
Yao (齐尧)

Re: [RFC] Use Doxygen for internals documentation

[Stan Shebs]

On 10/14/13 6:18 AM, Yao Qi wrote:
> On 10/12/2013 06:13 AM, Stan Shebs wrote:
>> This patch is the third and final step in the transition away from the
>> old GDB internals manual.

So people can take a look without installing the patch, I put a copy of
the output on github:

	http://stanshebs.github.io/gdb-doxy-test/


>>     doxy/gdb-api - GDB's "API", basically what is in .h files
>>     doxy/gdb-xref - the full xref, voluminous
> 
> Any reason to produce both of them?  I'd like to have a single one.

gdb-xref has the most information, but the cross-references can be
lengthy - in utils.h for instance, the references to gdb_stderr
etc fill multiple screens, and it's a distraction if you're just
looking for the right function to print a ULONGEST.

It wasn't obvious which one would be the most useful, and I didn't see
an option to "twist out" the API into a full xref, so I just ran it
twice.  If one of these is disliked, no problem to eliminate - hackers
can always create a personal page collection, doxygen is pretty fast
if you skip the macro expansion.

>>     doxy/gdbserver - GDBserver xref
>>     doxy/xml - XML version, for further script-crunching
> 
> Do you have an example that these xml files can be consumed by other tools?

Not yet, still learning the XML-fu necessary.  A couple easy examples
would be "find orphans" and "report the percentage of the API that has
been documented".

Stan
stan@codesourcery.com

Re: [RFC] Use Doxygen for internals documentation

[Tom Tromey]

>>>>> "Stan" == Stan Shebs <stanshebs@earthlink.net> writes:

Stan> This patch is the third and final step in the transition away from the
Stan> old GDB internals manual.

Thanks, Stan.

I applied your patch and built the docs locally.  This went smoothly.


I don't have a problem with the new way of formatting comments, or with
requiring them in review.

It seems to me that we should require docs for extern objects.  For
static objects I think it's fine to use less formal comments; but I'm
curious what others think.


Looking at the generated docs makes me wonder what knobs we have to
change the output.  Here's what I noticed:

I started by looking at the minsyms section.  I rearranged minsyms a
while back to have the comments in the header and to try to make it act
somewhat more like a self-contained module.  So, I was particularly
curious how this would render.

Starting here it looks promising enough:

    http://stanshebs.github.io/gdb-doxy-test/gdb-api/pages.html

(When we have two dozen modules here will we be able to organize them
somehow?)

Clicking through to the Minimal Symbols page, though, just gives some
text about the header.  (As an aside it's clear that this paragraph
needs a rewrite for Doxygen...)

However, there's nothing there about the module API, nor any link to
minsyms.h.  Is the latter something we can add?


I can go to the files page:

    http://stanshebs.github.io/gdb-doxy-test/gdb-api/files.html

and click through to minsyms.h:

    http://stanshebs.github.io/gdb-doxy-test/gdb-api/minsyms_8h.html

This lays out the contents of the file -- but not any introductory
text.  So that seems odd.

And, the contents are in an arbitrary order: Classes, Defines,
Functions.  What if we arranged the file in a particular order to
emphasize related things?  Could we reflect this in the docs somehow?

Finally, having to go to the Files page is sub-optimal just because it
presumes that one knows the layout.  It would be better if we could
start from some top-level view of "Modules of GDB" and click through to
the modules to understand their details.


I think it's fine to move forward even if all the answers are negative.
It's definitely an improvement.

Tom

Re: [RFC] Use Doxygen for internals documentation

[Stan Shebs]

On 10/16/13 10:28 AM, Tom Tromey wrote:
>>>>>> "Stan" == Stan Shebs <stanshebs@earthlink.net> writes:
> 
> Stan> This patch is the third and final step in the transition away from the
> Stan> old GDB internals manual.
> 
> Thanks, Stan.
> 
> I applied your patch and built the docs locally.  This went smoothly.
> 
> 
> I don't have a problem with the new way of formatting comments, or with
> requiring them in review.
> 
> It seems to me that we should require docs for extern objects.  For
> static objects I think it's fine to use less formal comments; but I'm
> curious what others think.

That's my working assumption as well.

> I started by looking at the minsyms section.  I rearranged minsyms a
> while back to have the comments in the header and to try to make it act
> somewhat more like a self-contained module.  So, I was particularly
> curious how this would render.
> 
> Starting here it looks promising enough:
> 
>     http://stanshebs.github.io/gdb-doxy-test/gdb-api/pages.html
> 
> (When we have two dozen modules here will we be able to organize them
> somehow?)
> 
> Clicking through to the Minimal Symbols page, though, just gives some
> text about the header.  (As an aside it's clear that this paragraph
> needs a rewrite for Doxygen...)
> 
> However, there's nothing there about the module API, nor any link to
> minsyms.h.  Is the latter something we can add?

Doxygen includes a scheme that basically lets you generate arbitrary
pages from block comments, and the Minimal Symbols page was my
experiment with that.  It doesn't seem to auto-generate any sort of
linkage to header file, but as part of arbitrariness there is the
ability to add links.  So that might have to be part of our practice
for such pages.

> I can go to the files page:
> 
>     http://stanshebs.github.io/gdb-doxy-test/gdb-api/files.html
> 
> and click through to minsyms.h:
> 
>     http://stanshebs.github.io/gdb-doxy-test/gdb-api/minsyms_8h.html
> 
> This lays out the contents of the file -- but not any introductory
> text.  So that seems odd.

Yeah, there doesn't seem to be a way to do that.

> And, the contents are in an arbitrary order: Classes, Defines,
> Functions.  What if we arranged the file in a particular order to
> emphasize related things?  Could we reflect this in the docs somehow?

There is a configuration option to list these in file order rather than
alphabetical, and there is some grouping machinery that I don't quite
understand yet.  There are HTML/CSS tricks that one can do as well,
so we have some options.

> Finally, having to go to the Files page is sub-optimal just because it
> presumes that one knows the layout.  It would be better if we could
> start from some top-level view of "Modules of GDB" and click through to
> the modules to understand their details.

Yeah, I think real deployment entails some kind of top-level page that
is the overall guide.

Another, more incremental approach is to have the API doxyfile list only
the files that have doxygen-type documentation.  So one grows
the doxyfile as more files get documented, and if foo-tdep.h never
gets official documentation, it's never clutter in the listing.

Stan

Re: [RFC] Use Doxygen for internals documentation

[Tom Tromey]

>>>>> "Stan" == Stan Shebs <stanshebs@earthlink.net> writes:

[...]
Stan> Yeah, I think real deployment entails some kind of top-level page that
Stan> is the overall guide.

Thanks for the responses.
I'm on board.

Stan> Another, more incremental approach is to have the API doxyfile list only
Stan> the files that have doxygen-type documentation.  So one grows
Stan> the doxyfile as more files get documented, and if foo-tdep.h never
Stan> gets official documentation, it's never clutter in the listing.

This sounds like a good default to me.

Tom

Re: [RFC] Use Doxygen for internals documentation

[Pedro Alves]

On 10/11/2013 11:13 PM, Stan Shebs wrote:
> 
> 1) Its parser get befuddled by some of our macrology.
...

> 3) The only way I could find to get Emacs to preserve our current
>    formatting rules is to have the opening "/**" on a line by itself.

GCC has these problems solved by running a simple filter on
the sources before feeding them to doxygen.  I think we
could/should do the same.

http://gcc.gnu.org/viewcvs/gcc/trunk/contrib/filter_params.pl?view=markup

1 	#!/usr/bin/perl
2 	
3 	# Filters out some of the #defines used throughout the GCC sources:
4 	# - GTY(()) marks declarations for gengtype.c
5 	# - PARAMS(()) is used for K&R compatibility. See ansidecl.h.
6 	
7 	while (<>) {
8 	s/^\/\* /\/\*\* \@verbatim /;
9 	s/\*\// \@endverbatim \*\//;
10 	s/GTY[ \t]*\(\(.*\)\)//g;
11 	s/[ \t]ATTRIBUTE_UNUSED//g;
12 	s/PARAMS[ \t]*\(\((.*?)\)\)/\($1\)/sg;
13 	print;
14 	}

David Malcolm just recently posted a gcc patch that rewrites
that in Python (and makes it smarter):

  http://gcc.gnu.org/ml/gcc-patches/2013-10/msg02728.html

-- 
Pedro Alves