Annotate comments for Doxygen.

2 files changed, 72 insertions, 64 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index b7c5c8a..e60ec1c 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,7 @@
+2014-02-25  Stan Shebs  <stan@codesourcery.com>
+
+	* defs.h: Annotate comments for Doxygen.
+
 2014-02-25  Tom Tromey  <tromey@redhat.com>
 
 	* target.h (target_ignore): Don't declare.
diff --git a/gdb/defs.h b/gdb/defs.h
index 1753dfa..480133d 100644
--- a/gdb/defs.h
+++ b/gdb/defs.h
@@ -103,13 +103,13 @@
 
 #include "bfd.h"
 
-/* A byte from the program being debugged.  */
+/* * A byte from the program being debugged.  */
 typedef bfd_byte gdb_byte;
 
-/* An address in the program being debugged.  Host byte order.  */
+/* * An address in the program being debugged.  Host byte order.  */
 typedef bfd_vma CORE_ADDR;
 
-/* The largest CORE_ADDR value.  */
+/* * The largest CORE_ADDR value.  */
 #define CORE_ADDR_MAX (~ (CORE_ADDR) 0)
 
 /* This is to make sure that LONGEST is at least as big as CORE_ADDR.  */
@@ -135,23 +135,23 @@ typedef bfd_vma CORE_ADDR;
 
 #include "ptid.h"
 
-/* Enable xdb commands if set.  */
+/* * Enable xdb commands if set.  */
 extern int xdb_commands;
 
-/* Enable dbx commands if set.  */
+/* * Enable dbx commands if set.  */
 extern int dbx_commands;
 
-/* System root path, used to find libraries etc.  */
+/* * System root path, used to find libraries etc.  */
 extern char *gdb_sysroot;
 
-/* GDB datadir, used to store data files.  */
+/* * GDB datadir, used to store data files.  */
 extern char *gdb_datadir;
 
-/* If non-NULL, the possibly relocated path to python's "lib" directory
+/* * If non-NULL, the possibly relocated path to python's "lib" directory
    specified with --with-python.  */
 extern char *python_libdir;
 
-/* Search path for separate debug files.  */
+/* * Search path for separate debug files.  */
 extern char *debug_file_directory;
 
 /* GDB has two methods for handling SIGINT.  When immediate_quit is
@@ -163,12 +163,12 @@ extern char *debug_file_directory;
    These functions use the extension_language_ops API to allow extension
    language(s) and GDB SIGINT handling to coexist seamlessly.  */
 
-/* Clear the quit flag.  */
+/* * Clear the quit flag.  */
 extern void clear_quit_flag (void);
-/* Evaluate to non-zero if the quit flag is set, zero otherwise.  This
+/* * Evaluate to non-zero if the quit flag is set, zero otherwise.  This
    will clear the quit flag as a side effect.  */
 extern int check_quit_flag (void);
-/* Set the quit flag.  */
+/* * Set the quit flag.  */
 extern void set_quit_flag (void);
 
 extern int immediate_quit;
@@ -187,7 +187,7 @@ extern void quit (void);
   if (deprecated_interactive_hook) deprecated_interactive_hook (); \
 }
 
-/* Languages represented in the symbol table and elsewhere.
+/* * Languages represented in the symbol table and elsewhere.
    This should probably be in language.h, but since enum's can't
    be forward declared to satisfy opaque references before their
    actual definition, needs to be here.  */
@@ -219,7 +219,8 @@ enum precision_type
     unspecified_precision
   };
 
-/* A generic, not quite boolean, enumeration.  */
+/* * A generic, not quite boolean, enumeration.  This is used for
+   set/show commands in which the options are on/off/automatic.  */
 enum auto_boolean
 {
   AUTO_BOOLEAN_TRUE,
@@ -227,26 +228,28 @@ enum auto_boolean
   AUTO_BOOLEAN_AUTO
 };
 
-/* Potential ways that a function can return a value of a given type.  */
+/* * Potential ways that a function can return a value of a given
+   type.  */
+
 enum return_value_convention
 {
-  /* Where the return value has been squeezed into one or more
+  /* * Where the return value has been squeezed into one or more
      registers.  */
   RETURN_VALUE_REGISTER_CONVENTION,
-  /* Commonly known as the "struct return convention".  The caller
+  /* * Commonly known as the "struct return convention".  The caller
      passes an additional hidden first parameter to the caller.  That
      parameter contains the address at which the value being returned
      should be stored.  While typically, and historically, used for
      large structs, this is convention is applied to values of many
      different types.  */
   RETURN_VALUE_STRUCT_CONVENTION,
-  /* Like the "struct return convention" above, but where the ABI
+  /* * Like the "struct return convention" above, but where the ABI
      guarantees that the called function stores the address at which
      the value being returned is stored in a well-defined location,
      such as a register or memory slot in the stack frame.  Don't use
      this if the ABI doesn't explicitly guarantees this.  */
   RETURN_VALUE_ABI_RETURNS_ADDRESS,
-  /* Like the "struct return convention" above, but where the ABI
+  /* * Like the "struct return convention" above, but where the ABI
      guarantees that the address at which the value being returned is
      stored will be available in a well-defined location, such as a
      register or memory slot in the stack frame.  Don't use this if
@@ -284,16 +287,16 @@ extern char *re_comp (const char *);
 
 extern void symbol_file_command (char *, int);
 
-/* Remote targets may wish to use this as their load function.  */
+/* * Remote targets may wish to use this as their load function.  */
 extern void generic_load (char *name, int from_tty);
 
-/* Report on STREAM the performance of memory transfer operation,
+/* * Report on STREAM the performance of memory transfer operation,
    such as 'load'.
-   DATA_COUNT is the number of bytes transferred.
-   WRITE_COUNT is the number of separate write operations, or 0,
+   @param DATA_COUNT is the number of bytes transferred.
+   @param WRITE_COUNT is the number of separate write operations, or 0,
    if that information is not available.
-   START_TIME is the time at which an operation was started.
-   END_TIME is the time at which an operation ended.  */
+   @param START_TIME is the time at which an operation was started.
+   @param END_TIME is the time at which an operation ended.  */
 struct timeval;
 extern void print_transfer_performance (struct ui_file *stream,
 					unsigned long data_count,
@@ -359,36 +362,37 @@ extern void init_source_path (void);
 
 /* From exec.c */
 
-/* Process memory area starting at ADDR with length SIZE.  Area is readable iff
-   READ is non-zero, writable if WRITE is non-zero, executable if EXEC is
-   non-zero.  Area is possibly changed against its original file based copy if
-   MODIFIED is non-zero.  DATA is passed without changes from a caller.  */
+/* * Process memory area starting at ADDR with length SIZE.  Area is
+   readable iff READ is non-zero, writable if WRITE is non-zero,
+   executable if EXEC is non-zero.  Area is possibly changed against
+   its original file based copy if MODIFIED is non-zero.  DATA is
+   passed without changes from a caller.  */
 
 typedef int (*find_memory_region_ftype) (CORE_ADDR addr, unsigned long size,
 					 int read, int write, int exec,
 					 int modified, void *data);
 
-/* Possible lvalue types.  Like enum language, this should be in
+/* * Possible lvalue types.  Like enum language, this should be in
    value.h, but needs to be here for the same reason.  */
 
 enum lval_type
   {
-    /* Not an lval.  */
+    /* * Not an lval.  */
     not_lval,
-    /* In memory.  */
+    /* * In memory.  */
     lval_memory,
-    /* In a register.  Registers are relative to a frame.  */
+    /* * In a register.  Registers are relative to a frame.  */
     lval_register,
-    /* In a gdb internal variable.  */
+    /* * In a gdb internal variable.  */
     lval_internalvar,
-    /* Part of a gdb internal variable (structure field).  */
+    /* * Part of a gdb internal variable (structure field).  */
     lval_internalvar_component,
-    /* Value's bits are fetched and stored using functions provided by
-       its creator.  */
+    /* * Value's bits are fetched and stored using functions provided
+       by its creator.  */
     lval_computed
   };
 
-/* Control types for commands */
+/* * Control types for commands.  */
 
 enum misc_command_type
   {
@@ -412,17 +416,17 @@ enum command_control_type
     invalid_control
   };
 
-/* Structure for saved commands lines
-   (for breakpoints, defined commands, etc).  */
+/* * Structure for saved commands lines (for breakpoints, defined
+   commands, etc).  */
 
 struct command_line
   {
     struct command_line *next;
     char *line;
     enum command_control_type control_type;
-    /* The number of elements in body_list.  */
+    /* * The number of elements in body_list.  */
     int body_count;
-    /* For composite commands, the nested lists of commands.  For
+    /* * For composite commands, the nested lists of commands.  For
        example, for "if" command this will contain the then branch and
        the else branch, if that is available.  */
     struct command_line **body_list;
@@ -437,44 +441,44 @@ extern struct command_line *read_command_lines_1 (char * (*) (void), int,
 
 extern void free_command_lines (struct command_line **);
 
-/* Parameters of the "info proc" command.  */
+/* * Parameters of the "info proc" command.  */
 
 enum info_proc_what
   {
-    /* Display the default cmdline, cwd and exe outputs.  */
+    /* * Display the default cmdline, cwd and exe outputs.  */
     IP_MINIMAL,
 
-    /* Display `info proc mappings'.  */
+    /* * Display `info proc mappings'.  */
     IP_MAPPINGS,
 
-    /* Display `info proc status'.  */
+    /* * Display `info proc status'.  */
     IP_STATUS,
 
-    /* Display `info proc stat'.  */
+    /* * Display `info proc stat'.  */
     IP_STAT,
 
-    /* Display `info proc cmdline'.  */
+    /* * Display `info proc cmdline'.  */
     IP_CMDLINE,
 
-    /* Display `info proc exe'.  */
+    /* * Display `info proc exe'.  */
     IP_EXE,
 
-    /* Display `info proc cwd'.  */
+    /* * Display `info proc cwd'.  */
     IP_CWD,
 
-    /* Display all of the above.  */
+    /* * Display all of the above.  */
     IP_ALL
   };
 
-/* String containing the current directory (what getwd would return).  */
+/* * String containing the current directory (what getwd would return).  */
 
 extern char *current_directory;
 
-/* Default radixes for input and output.  Only some values supported.  */
+/* * Default radixes for input and output.  Only some values supported.  */
 extern unsigned input_radix;
 extern unsigned output_radix;
 
-/* Possibilities for prettyformat parameters to routines which print
+/* * Possibilities for prettyformat parameters to routines which print
    things.  Like enum language, this should be in value.h, but needs
    to be here for the same reason.  FIXME:  If we can eliminate this
    as an arg to LA_VAL_PRINT, then we can probably move it back to
@@ -484,11 +488,11 @@ enum val_prettyformat
   {
     Val_no_prettyformat = 0,
     Val_prettyformat,
-    /* Use the default setting which the user has specified.  */
+    /* * Use the default setting which the user has specified.  */
     Val_prettyformat_default
   };
 
-/* Optional native machine support.  Non-native (and possibly pure
+/* * Optional native machine support.  Non-native (and possibly pure
    multi-arch) targets do not need a "nm.h" file.  This will be a
    symlink to one of the nm-*.h files, built by the `configure'
    script.  */
@@ -540,7 +544,7 @@ enum val_prettyformat
 #define	LONGEST_MAX ((LONGEST)(ULONGEST_MAX >> 1))
 #endif
 
-/* Convert a LONGEST to an int.  This is used in contexts (e.g. number of
+/* * Convert a LONGEST to an int.  This is used in contexts (e.g. number of
    arguments to a function, number in a value history, register number, etc.)
    where the value must not be larger than can fit in an int.  */
 
@@ -548,7 +552,7 @@ extern int longest_to_int (LONGEST);
 
 #include "common-utils.h"
 
-/* List of known OS ABIs.  If you change this, make sure to update the
+/* * List of known OS ABIs.  If you change this, make sure to update the
    table in osabi.c.  */
 enum gdb_osabi
 {
@@ -621,20 +625,20 @@ extern void *alloca ();
 /* Dynamic target-system-dependent parameters for GDB.  */
 #include "gdbarch.h"
 
-/* Maximum size of a register.  Something small, but large enough for
+/* * Maximum size of a register.  Something small, but large enough for
    all known ISAs.  If it turns out to be too small, make it bigger.  */
 
 enum { MAX_REGISTER_SIZE = 64 };
 
 /* Static target-system-dependent parameters for GDB.  */
 
-/* Number of bits in a char or unsigned char for the target machine.
+/* * Number of bits in a char or unsigned char for the target machine.
    Just like CHAR_BIT in <limits.h> but describes the target machine.  */
 #if !defined (TARGET_CHAR_BIT)
 #define TARGET_CHAR_BIT 8
 #endif
 
-/* If we picked up a copy of CHAR_BIT from a configuration file
+/* * If we picked up a copy of CHAR_BIT from a configuration file
    (which may get it by including <limits.h>) then use it to set
    the number of bits in a host char.  If not, use the same size
    as the target.  */
@@ -675,7 +679,7 @@ extern int watchdog;
 
 /* Hooks for alternate command interfaces.  */
 
-/* The name of the interpreter if specified on the command line.  */
+/* * The name of the interpreter if specified on the command line.  */
 extern char *interpreter_p;
 
 /* If a given interpreter matches INTERPRETER_P then it should update
@@ -728,7 +732,7 @@ extern int (*deprecated_ui_load_progress_hook) (const char *section,
 #define ISATTY(FP)	(isatty (fileno (FP)))
 #endif
 
-/* A width that can achieve a better legibility for GDB MI mode.  */
+/* * A width that can achieve a better legibility for GDB MI mode.  */
 #define GDB_MI_MSG_WIDTH  80
 
 /* From progspace.c */
@@ -736,7 +740,7 @@ extern int (*deprecated_ui_load_progress_hook) (const char *section,
 extern void initialize_progspace (void);
 extern void initialize_inferiors (void);
 
-/* Special block numbers */
+/* * Special block numbers */
 
 enum block_enum
 {