Doxygenate gdbtypes.h

4 files changed, 460 insertions, 350 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index ccc226e..b1f4b50 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,8 @@
+2014-03-12  Stan Shebs  <stan@codesourcery.com>
+
+	* gdbtypes.h: Annotate comments for Doxygen, add a page
+	block comment with some general info.
+
 2014-03-12  Pedro Alves  <palves@redhat.com>
 
 	* infcmd.c (prepare_execution_command): New function, factored out
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 47f5f38..bcf5ab7 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,7 @@
+2014-03-12  Stan Shebs  <stan@codesourcery.com>
+
+	* Doxyfile-gdb-api.in (INPUT): Add gdbtypes.h.
+
 2014-02-26  Ludovic Courtès  <ludo@gnu.org>
 
 	* gdb/doc/guile.texi (Basic Guile): Document 'history-append!'.
diff --git a/gdb/doc/Doxyfile-gdb-api.in b/gdb/doc/Doxyfile-gdb-api.in
index 02f8bdd..1420464 100644
--- a/gdb/doc/Doxyfile-gdb-api.in
+++ b/gdb/doc/Doxyfile-gdb-api.in
@@ -27,6 +27,7 @@ PROJECT_NAME = "GDB (API)"
 # everything.)
 
 INPUT = @srcdir@/../defs.h \
+        @srcdir@/../gdbtypes.h \
         @srcdir@/../minsyms.h \
         @srcdir@/../utils.h
 
diff --git a/gdb/gdbtypes.h b/gdb/gdbtypes.h
index 080c3eb..c6943ef 100644
--- a/gdb/gdbtypes.h
+++ b/gdb/gdbtypes.h
@@ -22,6 +22,26 @@
 #if !defined (GDBTYPES_H)
 #define GDBTYPES_H 1
 
+/* * \page gdbtypes GDB Types
+
+   GDB represents all the different kinds of types in programming
+   languages using a common representation defined in gdbtypes.h.
+
+   The main data structure is main_type; it consists of a code (such
+   as TYPE_CODE_ENUM for enumeration types), a number of
+   generally-useful fields such as the printable name, and finally a
+   field type_specific that is a union of info specific to particular
+   languages or other special cases (such as calling convention).
+
+   The available type codes are defined in enum type_code.  The enum
+   includes codes both for types that are common across a variety
+   of languages, and for types that are language-specific.
+
+   Most accesses to type fields go through macros such as TYPE_CODE
+   and TYPE_FN_FIELD_CONST.  These are written such that they can be
+   used as both rvalues and lvalues.
+ */
+
 #include "hashtab.h"
 
 /* Forward declarations for prototypes.  */
@@ -33,13 +53,16 @@ struct language_defn;
 /* These declarations are DWARF-specific as some of the gdbtypes.h data types
    are already DWARF-specific.  */
 
-/* Offset relative to the start of its containing CU (compilation unit).  */
+/* * Offset relative to the start of its containing CU (compilation
+   unit).  */
 typedef struct
 {
   unsigned int cu_off;
 } cu_offset;
 
-/* Offset relative to the start of its .debug_info or .debug_types section.  */
+/* * Offset relative to the start of its .debug_info or .debug_types
+   section.  */
+
 typedef struct
 {
   unsigned int sect_off;
@@ -54,15 +77,16 @@ typedef struct
 #define	B_BYTES(x)	( 1 + ((x)>>3) )
 #define	B_CLRALL(a,x)	memset ((a), 0, B_BYTES(x))
 
-/* Different kinds of data types are distinguished by the `code' field.  */
+/* * Different kinds of data types are distinguished by the `code'
+   field.  */
 
 enum type_code
   {
-    TYPE_CODE_BITSTRING = -1,	/* Deprecated  */
-    TYPE_CODE_UNDEF = 0,	/* Not used; catches errors */
-    TYPE_CODE_PTR,		/* Pointer type */
+    TYPE_CODE_BITSTRING = -1,	/**< Deprecated  */
+    TYPE_CODE_UNDEF = 0,	/**< Not used; catches errors */
+    TYPE_CODE_PTR,		/**< Pointer type */
 
-    /* Array type with lower & upper bounds.
+    /* * Array type with lower & upper bounds.
 
        Regardless of the language, GDB represents multidimensional
        array types the way C does: as arrays of arrays.  So an
@@ -82,85 +106,90 @@ enum type_code
        from right to left, not left to right.  */
     TYPE_CODE_ARRAY,
 
-    TYPE_CODE_STRUCT,		/* C struct or Pascal record */
-    TYPE_CODE_UNION,		/* C union or Pascal variant part */
-    TYPE_CODE_ENUM,		/* Enumeration type */
-    TYPE_CODE_FLAGS,		/* Bit flags type */
-    TYPE_CODE_FUNC,		/* Function type */
-    TYPE_CODE_INT,		/* Integer type */
+    TYPE_CODE_STRUCT,		/**< C struct or Pascal record */
+    TYPE_CODE_UNION,		/**< C union or Pascal variant part */
+    TYPE_CODE_ENUM,		/**< Enumeration type */
+    TYPE_CODE_FLAGS,		/**< Bit flags type */
+    TYPE_CODE_FUNC,		/**< Function type */
+    TYPE_CODE_INT,		/**< Integer type */
 
-    /* Floating type.  This is *NOT* a complex type.  Beware, there are parts
-       of GDB which bogusly assume that TYPE_CODE_FLT can mean complex.  */
+    /* * Floating type.  This is *NOT* a complex type.  Beware, there
+       are parts of GDB which bogusly assume that TYPE_CODE_FLT can
+       mean complex.  */
     TYPE_CODE_FLT,
 
-    /* Void type.  The length field specifies the length (probably always
-       one) which is used in pointer arithmetic involving pointers to
-       this type, but actually dereferencing such a pointer is invalid;
-       a void type has no length and no actual representation in memory
-       or registers.  A pointer to a void type is a generic pointer.  */
+    /* * Void type.  The length field specifies the length (probably
+       always one) which is used in pointer arithmetic involving
+       pointers to this type, but actually dereferencing such a
+       pointer is invalid; a void type has no length and no actual
+       representation in memory or registers.  A pointer to a void
+       type is a generic pointer.  */
     TYPE_CODE_VOID,
 
-    TYPE_CODE_SET,		/* Pascal sets */
-    TYPE_CODE_RANGE,		/* Range (integers within spec'd bounds).  */
+    TYPE_CODE_SET,		/**< Pascal sets */
+    TYPE_CODE_RANGE,		/**< Range (integers within spec'd bounds).  */
 
-    /* A string type which is like an array of character but prints
+    /* * A string type which is like an array of character but prints
        differently (at least for (the deleted) CHILL).  It does not
        contain a length field as Pascal strings (for many Pascals,
        anyway) do; if we want to deal with such strings, we should use
        a new type code.  */
     TYPE_CODE_STRING,
 
-    /* Unknown type.  The length field is valid if we were able to
-       deduce that much about the type, or 0 if we don't even know that.  */
+    /* * Unknown type.  The length field is valid if we were able to
+       deduce that much about the type, or 0 if we don't even know
+       that.  */
     TYPE_CODE_ERROR,
 
     /* C++ */
-    TYPE_CODE_METHOD,		/* Method type */
+    TYPE_CODE_METHOD,		/**< Method type */
 
-    /* Pointer-to-member-function type.  This describes how to access a
+    /* * Pointer-to-member-function type.  This describes how to access a
        particular member function of a class (possibly a virtual
        member function).  The representation may vary between different
        C++ ABIs.  */
     TYPE_CODE_METHODPTR,
 
-    /* Pointer-to-member type.  This is the offset within a class to some
-       particular data member.  The only currently supported representation
-       uses an unbiased offset, with -1 representing NULL; this is used
-       by the Itanium C++ ABI (used by GCC on all platforms).  */
+    /* * Pointer-to-member type.  This is the offset within a class to
+       some particular data member.  The only currently supported
+       representation uses an unbiased offset, with -1 representing
+       NULL; this is used by the Itanium C++ ABI (used by GCC on all
+       platforms).  */
     TYPE_CODE_MEMBERPTR,
 
-    TYPE_CODE_REF,		/* C++ Reference types */
+    TYPE_CODE_REF,		/**< C++ Reference types */
 
-    TYPE_CODE_CHAR,		/* *real* character type */
+    TYPE_CODE_CHAR,		/**< *real* character type */
 
-    /* Boolean type.  0 is false, 1 is true, and other values are non-boolean
-       (e.g. FORTRAN "logical" used as unsigned int).  */
+    /* * Boolean type.  0 is false, 1 is true, and other values are
+       non-boolean (e.g. FORTRAN "logical" used as unsigned int).  */
     TYPE_CODE_BOOL,
 
     /* Fortran */
-    TYPE_CODE_COMPLEX,		/* Complex float */
+    TYPE_CODE_COMPLEX,		/**< Complex float */
 
     TYPE_CODE_TYPEDEF,
 
-    TYPE_CODE_NAMESPACE,	/* C++ namespace.  */
+    TYPE_CODE_NAMESPACE,	/**< C++ namespace.  */
 
-    TYPE_CODE_DECFLOAT,		/* Decimal floating point.  */
+    TYPE_CODE_DECFLOAT,		/**< Decimal floating point.  */
 
-    TYPE_CODE_MODULE,		/* Fortran module.  */
+    TYPE_CODE_MODULE,		/**< Fortran module.  */
 
-    /* Internal function type.  */
+    /* * Internal function type.  */
     TYPE_CODE_INTERNAL_FUNCTION
   };
 
-/* For now allow source to use TYPE_CODE_CLASS for C++ classes, as an
-   alias for TYPE_CODE_STRUCT.  This is for DWARF, which has a distinct
-   "class" attribute.  Perhaps we should actually have a separate TYPE_CODE
-   so that we can print "class" or "struct" depending on what the debug
-   info said.  It's not clear we should bother.  */
+/* * For now allow source to use TYPE_CODE_CLASS for C++ classes, as
+   an alias for TYPE_CODE_STRUCT.  This is for DWARF, which has a
+   distinct "class" attribute.  Perhaps we should actually have a
+   separate TYPE_CODE so that we can print "class" or "struct"
+   depending on what the debug info said.  It's not clear we should
+   bother.  */
 
 #define TYPE_CODE_CLASS TYPE_CODE_STRUCT
 
-/* Some constants representing each bit field in the main_type.  See
+/* * Some constants representing each bit field in the main_type.  See
    the bit-field-specific macros, below, for documentation of each
    constant in this enum.  These enum values are only used with
    init_type.  Note that the values are chosen not to conflict with
@@ -182,13 +211,14 @@ enum type_flag_value
   TYPE_FLAG_STUB_SUPPORTED = (1 << 18),
   TYPE_FLAG_GNU_IFUNC = (1 << 19),
 
-  /* Used for error-checking.  */
+  /* * Used for error-checking.  */
   TYPE_FLAG_MIN = TYPE_FLAG_UNSIGNED
 };
 
-/* Some bits for the type's instance_flags word.  See the macros below
-   for documentation on each bit.  Note that if you add a value here,
-   you must update the enum type_flag_value as well.  */
+/* * Some bits for the type's instance_flags word.  See the macros
+   below for documentation on each bit.  Note that if you add a value
+   here, you must update the enum type_flag_value as well.  */
+
 enum type_instance_flag_value
 {
   TYPE_INSTANCE_FLAG_CONST = (1 << 0),
@@ -201,46 +231,46 @@ enum type_instance_flag_value
   TYPE_INSTANCE_FLAG_RESTRICT = (1 << 7)
 };
 
-/* Unsigned integer type.  If this is not set for a TYPE_CODE_INT, the
-   type is signed (unless TYPE_FLAG_NOSIGN (below) is set).  */
+/* * Unsigned integer type.  If this is not set for a TYPE_CODE_INT,
+   the type is signed (unless TYPE_FLAG_NOSIGN (below) is set).  */
 
 #define TYPE_UNSIGNED(t)	(TYPE_MAIN_TYPE (t)->flag_unsigned)
 
-/* No sign for this type.  In C++, "char", "signed char", and "unsigned
-   char" are distinct types; so we need an extra flag to indicate the
-   absence of a sign!  */
+/* * No sign for this type.  In C++, "char", "signed char", and
+   "unsigned char" are distinct types; so we need an extra flag to
+   indicate the absence of a sign!  */
 
 #define TYPE_NOSIGN(t)		(TYPE_MAIN_TYPE (t)->flag_nosign)
 
-/* This appears in a type's flags word if it is a stub type (e.g., if
-   someone referenced a type that wasn't defined in a source file
+/* * This appears in a type's flags word if it is a stub type (e.g.,
+   if someone referenced a type that wasn't defined in a source file
    via (struct sir_not_appearing_in_this_film *)).  */
 
 #define TYPE_STUB(t)		(TYPE_MAIN_TYPE (t)->flag_stub)
 
-/* The target type of this type is a stub type, and this type needs to
-   be updated if it gets un-stubbed in check_typedef.
-   Used for arrays and ranges, in which TYPE_LENGTH of the array/range
-   gets set based on the TYPE_LENGTH of the target type.
-   Also, set for TYPE_CODE_TYPEDEF.  */
+/* * The target type of this type is a stub type, and this type needs
+   to be updated if it gets un-stubbed in check_typedef.  Used for
+   arrays and ranges, in which TYPE_LENGTH of the array/range gets set
+   based on the TYPE_LENGTH of the target type.  Also, set for
+   TYPE_CODE_TYPEDEF.  */
 
 #define TYPE_TARGET_STUB(t)	(TYPE_MAIN_TYPE (t)->flag_target_stub)
 
-/* Static type.  If this is set, the corresponding type had 
+/* * Static type.  If this is set, the corresponding type had 
    a static modifier.
    Note: This may be unnecessary, since static data members
    are indicated by other means (bitpos == -1).  */
 
 #define TYPE_STATIC(t)		(TYPE_MAIN_TYPE (t)->flag_static)
 
-/* This is a function type which appears to have a prototype.  We need
-   this for function calls in order to tell us if it's necessary to
-   coerce the args, or to just do the standard conversions.  This is
-   used with a short field.  */
+/* * This is a function type which appears to have a prototype.  We
+   need this for function calls in order to tell us if it's necessary
+   to coerce the args, or to just do the standard conversions.  This
+   is used with a short field.  */
 
 #define TYPE_PROTOTYPED(t)	(TYPE_MAIN_TYPE (t)->flag_prototyped)
 
-/* This flag is used to indicate that processing for this type
+/* * This flag is used to indicate that processing for this type
    is incomplete.
 
    (Mostly intended for HP platforms, where class methods, for
@@ -250,46 +280,48 @@ enum type_instance_flag_value
 
 #define TYPE_INCOMPLETE(t)	(TYPE_MAIN_TYPE (t)->flag_incomplete)
 
-/* FIXME drow/2002-06-03:  Only used for methods, but applies as well
+/* * FIXME drow/2002-06-03:  Only used for methods, but applies as well
    to functions.  */
 
 #define TYPE_VARARGS(t)		(TYPE_MAIN_TYPE (t)->flag_varargs)
 
-/* Identify a vector type.  Gcc is handling this by adding an extra
+/* * Identify a vector type.  Gcc is handling this by adding an extra
    attribute to the array type.  We slurp that in as a new flag of a
    type.  This is used only in dwarf2read.c.  */
 #define TYPE_VECTOR(t)		(TYPE_MAIN_TYPE (t)->flag_vector)
 
-/* The debugging formats (especially STABS) do not contain enough information
-   to represent all Ada types---especially those whose size depends on
-   dynamic quantities.  Therefore, the GNAT Ada compiler includes
-   extra information in the form of additional type definitions
-   connected by naming conventions.  This flag indicates that the 
-   type is an ordinary (unencoded) GDB type that has been created from 
-   the necessary run-time information, and does not need further 
-   interpretation.  Optionally marks ordinary, fixed-size GDB type.  */
+/* * The debugging formats (especially STABS) do not contain enough
+   information to represent all Ada types---especially those whose
+   size depends on dynamic quantities.  Therefore, the GNAT Ada
+   compiler includes extra information in the form of additional type
+   definitions connected by naming conventions.  This flag indicates
+   that the type is an ordinary (unencoded) GDB type that has been
+   created from the necessary run-time information, and does not need
+   further interpretation.  Optionally marks ordinary, fixed-size GDB
+   type.  */
 
 #define TYPE_FIXED_INSTANCE(t) (TYPE_MAIN_TYPE (t)->flag_fixed_instance)
 
-/* This debug target supports TYPE_STUB(t).  In the unsupported case we have to
-   rely on NFIELDS to be zero etc., see TYPE_IS_OPAQUE ().
-   TYPE_STUB(t) with !TYPE_STUB_SUPPORTED(t) may exist if we only guessed
-   the TYPE_STUB(t) value (see dwarfread.c).  */
+/* * This debug target supports TYPE_STUB(t).  In the unsupported case
+   we have to rely on NFIELDS to be zero etc., see TYPE_IS_OPAQUE().
+   TYPE_STUB(t) with !TYPE_STUB_SUPPORTED(t) may exist if we only
+   guessed the TYPE_STUB(t) value (see dwarfread.c).  */
 
 #define TYPE_STUB_SUPPORTED(t)   (TYPE_MAIN_TYPE (t)->flag_stub_supported)
 
-/* Not textual.  By default, GDB treats all single byte integers as
+/* * Not textual.  By default, GDB treats all single byte integers as
    characters (or elements of strings) unless this flag is set.  */
 
 #define TYPE_NOTTEXT(t)	(TYPE_INSTANCE_FLAGS (t) & TYPE_INSTANCE_FLAG_NOTTEXT)
 
-/* Used only for TYPE_CODE_FUNC where it specifies the real function
-   address is returned by this function call.  TYPE_TARGET_TYPE determines the
-   final returned function type to be presented to user.  */
+/* * Used only for TYPE_CODE_FUNC where it specifies the real function
+   address is returned by this function call.  TYPE_TARGET_TYPE
+   determines the final returned function type to be presented to
+   user.  */
 
 #define TYPE_GNU_IFUNC(t)	(TYPE_MAIN_TYPE (t)->flag_gnu_ifunc)
 
-/* Type owner.  If TYPE_OBJFILE_OWNED is true, the type is owned by
+/* * Type owner.  If TYPE_OBJFILE_OWNED is true, the type is owned by
    the objfile retrieved as TYPE_OBJFILE.  Otherweise, the type is
    owned by an architecture; TYPE_OBJFILE is NULL in this case.  */
 
@@ -297,36 +329,36 @@ enum type_instance_flag_value
 #define TYPE_OWNER(t) TYPE_MAIN_TYPE(t)->owner
 #define TYPE_OBJFILE(t) (TYPE_OBJFILE_OWNED(t)? TYPE_OWNER(t).objfile : NULL)
 
-/* True if this type was declared using the "class" keyword.  This is
+/* * True if this type was declared using the "class" keyword.  This is
    only valid for C++ structure types, and only used for displaying
    the type.  If false, the structure was declared as a "struct".  */
 
 #define TYPE_DECLARED_CLASS(t) (TYPE_MAIN_TYPE (t)->flag_declared_class)
 
-/* True if this type is a "flag" enum.  A flag enum is one where all
+/* * True if this type is a "flag" enum.  A flag enum is one where all
    the values are pairwise disjoint when "and"ed together.  This
    affects how enum values are printed.  */
 
 #define TYPE_FLAG_ENUM(t) (TYPE_MAIN_TYPE (t)->flag_flag_enum)
 
-/* Constant type.  If this is set, the corresponding type has a
+/* * Constant type.  If this is set, the corresponding type has a
    const modifier.  */
 
 #define TYPE_CONST(t) (TYPE_INSTANCE_FLAGS (t) & TYPE_INSTANCE_FLAG_CONST)
 
-/* Volatile type.  If this is set, the corresponding type has a
+/* * Volatile type.  If this is set, the corresponding type has a
    volatile modifier.  */
 
 #define TYPE_VOLATILE(t) \
   (TYPE_INSTANCE_FLAGS (t) & TYPE_INSTANCE_FLAG_VOLATILE)
 
-/* Restrict type.  If this is set, the corresponding type has a
+/* * Restrict type.  If this is set, the corresponding type has a
    restrict modifier.  */
 
 #define TYPE_RESTRICT(t) \
   (TYPE_INSTANCE_FLAGS (t) & TYPE_INSTANCE_FLAG_RESTRICT)
 
-/* Instruction-space delimited type.  This is for Harvard architectures
+/* * Instruction-space delimited type.  This is for Harvard architectures
    which have separate instruction and data address spaces (and perhaps
    others).
 
@@ -351,11 +383,13 @@ enum type_instance_flag_value
 #define TYPE_DATA_SPACE(t) \
   (TYPE_INSTANCE_FLAGS (t) & TYPE_INSTANCE_FLAG_DATA_SPACE)
 
-/* Address class flags.  Some environments provide for pointers whose
-   size is different from that of a normal pointer or address types
-   where the bits are interpreted differently than normal addresses.  The
-   TYPE_FLAG_ADDRESS_CLASS_n flags may be used in target specific
-   ways to represent these different types of address classes.  */
+/* * Address class flags.  Some environments provide for pointers
+   whose size is different from that of a normal pointer or address
+   types where the bits are interpreted differently than normal
+   addresses.  The TYPE_FLAG_ADDRESS_CLASS_n flags may be used in
+   target specific ways to represent these different types of address
+   classes.  */
+
 #define TYPE_ADDRESS_CLASS_1(t) (TYPE_INSTANCE_FLAGS(t) \
                                  & TYPE_INSTANCE_FLAG_ADDRESS_CLASS_1)
 #define TYPE_ADDRESS_CLASS_2(t) (TYPE_INSTANCE_FLAGS(t) \
@@ -365,19 +399,20 @@ enum type_instance_flag_value
 #define TYPE_ADDRESS_CLASS_ALL(t) (TYPE_INSTANCE_FLAGS(t) \
 				   & TYPE_INSTANCE_FLAG_ADDRESS_CLASS_ALL)
 
-/* Determine which field of the union main_type.fields[x].loc is used.  */
+/* * Determine which field of the union main_type.fields[x].loc is
+   used.  */
 
 enum field_loc_kind
   {
-    FIELD_LOC_KIND_BITPOS,	/* bitpos */
-    FIELD_LOC_KIND_ENUMVAL,	/* enumval */
-    FIELD_LOC_KIND_PHYSADDR,	/* physaddr */
-    FIELD_LOC_KIND_PHYSNAME,	/* physname */
-    FIELD_LOC_KIND_DWARF_BLOCK	/* dwarf_block */
+    FIELD_LOC_KIND_BITPOS,	/**< bitpos */
+    FIELD_LOC_KIND_ENUMVAL,	/**< enumval */
+    FIELD_LOC_KIND_PHYSADDR,	/**< physaddr */
+    FIELD_LOC_KIND_PHYSNAME,	/**< physname */
+    FIELD_LOC_KIND_DWARF_BLOCK	/**< dwarf_block */
   };
 
-/* A discriminant to determine which field in the main_type.type_specific
-   union is being used, if any.
+/* * A discriminant to determine which field in the
+   main_type.type_specific union is being used, if any.
 
    For types such as TYPE_CODE_FLT or TYPE_CODE_FUNC, the use of this
    discriminant is really redundant, as we know from the type code
@@ -396,16 +431,18 @@ enum type_specific_kind
   TYPE_SPECIFIC_FUNC
 };
 
-/* This structure is space-critical.
-   Its layout has been tweaked to reduce the space used.  */
+/* * Main structure representing a type in GDB.
+
+   This structure is space-critical.  Its layout has been tweaked to
+   reduce the space used.  */
 
 struct main_type
 {
-  /* Code for kind of type.  */
+  /* * Code for kind of type.  */
 
   ENUM_BITFIELD(type_code) code : 8;
 
-  /* Flags about this type.  These fields appear at this location
+  /* * Flags about this type.  These fields appear at this location
      because they packs nicely here.  See the TYPE_* macros for
      documentation about these fields.  */
 
@@ -422,30 +459,33 @@ struct main_type
   unsigned int flag_gnu_ifunc : 1;
   unsigned int flag_fixed_instance : 1;
   unsigned int flag_objfile_owned : 1;
-  /* True if this type was declared with "class" rather than
+
+  /* * True if this type was declared with "class" rather than
      "struct".  */
+
   unsigned int flag_declared_class : 1;
 
-  /* True if this is an enum type with disjoint values.  This affects
-     how the enum is printed.  */
+  /* * True if this is an enum type with disjoint values.  This
+     affects how the enum is printed.  */
 
   unsigned int flag_flag_enum : 1;
 
-  /* A discriminant telling us which field of the type_specific union
-     is being used for this type, if any.  */
+  /* * A discriminant telling us which field of the type_specific
+     union is being used for this type, if any.  */
+
   ENUM_BITFIELD(type_specific_kind) type_specific_field : 3;
 
-  /* Number of fields described for this type.  This field appears at
-     this location because it packs nicely here.  */
+  /* * Number of fields described for this type.  This field appears
+     at this location because it packs nicely here.  */
 
   short nfields;
 
-  /* Field number of the virtual function table pointer in
+  /* * Field number of the virtual function table pointer in
      VPTR_BASETYPE.  If -1, we were unable to find the virtual
      function table pointer in initial symbol reading, and
      get_vptr_fieldno should be called to find it if possible.
-     get_vptr_fieldno will update this field if possible.
-     Otherwise the value is left at -1.
+     get_vptr_fieldno will update this field if possible.  Otherwise
+     the value is left at -1.
 
      Unused if this type does not have virtual functions.
 
@@ -453,20 +493,20 @@ struct main_type
 
   short vptr_fieldno;
 
-  /* Name of this type, or NULL if none.
+  /* * Name of this type, or NULL if none.
 
-     This is used for printing only, except by poorly designed C++ code.
-     For looking up a name, look for a symbol in the VAR_DOMAIN.
-     This is generally allocated in the objfile's obstack.
-     However coffread.c uses malloc.  */
+     This is used for printing only, except by poorly designed C++
+     code.  For looking up a name, look for a symbol in the
+     VAR_DOMAIN.  This is generally allocated in the objfile's
+     obstack.  However coffread.c uses malloc.  */
 
   const char *name;
 
-  /* Tag name for this type, or NULL if none.  This means that the
+  /* * Tag name for this type, or NULL if none.  This means that the
      name of the type consists of a keyword followed by the tag name.
      Which keyword is determined by the type code ("struct" for
-     TYPE_CODE_STRUCT, etc.).  As far as I know C/C++ are the only languages
-     with this feature.
+     TYPE_CODE_STRUCT, etc.).  As far as I know C/C++ are the only
+     languages with this feature.
 
      This is used for printing only, except by poorly designed C++ code.
      For looking up a name, look for a symbol in the STRUCT_DOMAIN.
@@ -475,17 +515,17 @@ struct main_type
 
   const char *tag_name;
 
-  /* Every type is now associated with a particular objfile, and the
-     type is allocated on the objfile_obstack for that objfile.  One problem
-     however, is that there are times when gdb allocates new types while
-     it is not in the process of reading symbols from a particular objfile.
-     Fortunately, these happen when the type being created is a derived
-     type of an existing type, such as in lookup_pointer_type().  So
-     we can just allocate the new type using the same objfile as the
-     existing type, but to do this we need a backpointer to the objfile
-     from the existing type.  Yes this is somewhat ugly, but without
-     major overhaul of the internal type system, it can't be avoided
-     for now.  */
+  /* * Every type is now associated with a particular objfile, and the
+     type is allocated on the objfile_obstack for that objfile.  One
+     problem however, is that there are times when gdb allocates new
+     types while it is not in the process of reading symbols from a
+     particular objfile.  Fortunately, these happen when the type
+     being created is a derived type of an existing type, such as in
+     lookup_pointer_type().  So we can just allocate the new type
+     using the same objfile as the existing type, but to do this we
+     need a backpointer to the objfile from the existing type.  Yes
+     this is somewhat ugly, but without major overhaul of the internal
+     type system, it can't be avoided for now.  */
 
   union type_owner
     {
@@ -493,19 +533,19 @@ struct main_type
       struct gdbarch *gdbarch;
     } owner;
 
-  /* For a pointer type, describes the type of object pointed to.
-     For an array type, describes the type of the elements.
-     For a function or method type, describes the type of the return value.
-     For a range type, describes the type of the full range.
-     For a complex type, describes the type of each coordinate.
-     For a special record or union type encoding a dynamic-sized type
+  /* * For a pointer type, describes the type of object pointed to.
+     - For an array type, describes the type of the elements.
+     - For a function or method type, describes the type of the return value.
+     - For a range type, describes the type of the full range.
+     - For a complex type, describes the type of each coordinate.
+     - For a special record or union type encoding a dynamic-sized type
      in GNAT, a memoized pointer to a corresponding static version of
      the type.
-     Unused otherwise.  */
+     - Unused otherwise.  */
 
   struct type *target_type;
 
-  /* For structure and union types, a description of each field.
+  /* * For structure and union types, a description of each field.
      For set and pascal array types, there is one "field",
      whose type is the domain type of the set or array.
      For range types, there are two "fields",
@@ -527,7 +567,7 @@ struct main_type
     {
       union field_location
       {
-	/* Position of this field, counting in bits from start of
+	/* * Position of this field, counting in bits from start of
 	   containing structure.  For gdbarch_bits_big_endian=1
 	   targets, it is the bit offset to the MSB.  For
 	   gdbarch_bits_big_endian=0 targets, it is the bit offset to
@@ -535,34 +575,35 @@ struct main_type
 
 	int bitpos;
 
-	/* Enum value.  */
+	/* * Enum value.  */
 	LONGEST enumval;
 
-	/* For a static field, if TYPE_FIELD_STATIC_HAS_ADDR then physaddr
-	   is the location (in the target) of the static field.
-	   Otherwise, physname is the mangled label of the static field.  */
+	/* * For a static field, if TYPE_FIELD_STATIC_HAS_ADDR then
+	   physaddr is the location (in the target) of the static
+	   field.  Otherwise, physname is the mangled label of the
+	   static field.  */
 
 	CORE_ADDR physaddr;
 	const char *physname;
 
-	/* The field location can be computed by evaluating the following DWARF
-	   block.  Its DATA is allocated on objfile_obstack - no CU load is
-	   needed to access it.  */
+	/* * The field location can be computed by evaluating the
+	   following DWARF block.  Its DATA is allocated on
+	   objfile_obstack - no CU load is needed to access it.  */
 
 	struct dwarf2_locexpr_baton *dwarf_block;
       }
       loc;
 
-      /* For a function or member type, this is 1 if the argument is marked
-	 artificial.  Artificial arguments should not be shown to the
-	 user.  For TYPE_CODE_RANGE it is set if the specific bound is not
-	 defined.  */
+      /* * For a function or member type, this is 1 if the argument is
+	 marked artificial.  Artificial arguments should not be shown
+	 to the user.  For TYPE_CODE_RANGE it is set if the specific
+	 bound is not defined.  */
       unsigned int artificial : 1;
 
-      /* Discriminant for union field_location.  */
+      /* * Discriminant for union field_location.  */
       ENUM_BITFIELD(field_loc_kind) loc_kind : 3;
 
-      /* Size of this field, in bits, or zero if not packed.
+      /* * Size of this field, in bits, or zero if not packed.
 	 If non-zero in an array type, indicates the element size in
 	 bits (used only in Ada at the moment).
 	 For an unpacked field, the field's type's length
@@ -570,32 +611,32 @@ struct main_type
 
       unsigned int bitsize : 28;
 
-      /* In a struct or union type, type of this field.
-	 In a function or member type, type of this argument.
-	 In an array type, the domain-type of the array.  */
+      /* * In a struct or union type, type of this field.
+	 - In a function or member type, type of this argument.
+	 - In an array type, the domain-type of the array.  */
 
       struct type *type;
 
-      /* Name of field, value or argument.
+      /* * Name of field, value or argument.
 	 NULL for range bounds, array domains, and member function
 	 arguments.  */
 
       const char *name;
     } *fields;
 
-    /* Union member used for range types.  */
+    /* * Union member used for range types.  */
 
     struct range_bounds
     {
-      /* Low bound of range.  */
+      /* * Low bound of range.  */
 
       LONGEST low;
 
-      /* High bound of range.  */
+      /* * High bound of range.  */
 
       LONGEST high;
 
-      /* Flags indicating whether the values of low and high are
+      /* * Flags indicating whether the values of low and high are
          valid.  When true, the respective range value is
          undefined.  Currently used only for FORTRAN arrays.  */
            
@@ -606,8 +647,9 @@ struct main_type
 
   } flds_bnds;
 
-  /* For types with virtual functions (TYPE_CODE_STRUCT), VPTR_BASETYPE
-     is the base class which defined the virtual function table pointer.  
+  /* * For types with virtual functions (TYPE_CODE_STRUCT),
+     VPTR_BASETYPE is the base class which defined the virtual
+     function table pointer.
 
      For types that are pointer to member types (TYPE_CODE_METHODPTR,
      TYPE_CODE_MEMBERPTR), VPTR_BASETYPE is the type that this pointer
@@ -620,73 +662,80 @@ struct main_type
 
   struct type *vptr_basetype;
 
-  /* Slot to point to additional language-specific fields of this type.  */
+  /* * Slot to point to additional language-specific fields of this
+     type.  */
 
   union type_specific
   {
-    /* CPLUS_STUFF is for TYPE_CODE_STRUCT.  It is initialized to point to
-       cplus_struct_default, a default static instance of a struct
-       cplus_struct_type.  */
+    /* * CPLUS_STUFF is for TYPE_CODE_STRUCT.  It is initialized to
+       point to cplus_struct_default, a default static instance of a
+       struct cplus_struct_type.  */
 
     struct cplus_struct_type *cplus_stuff;
 
-    /* GNAT_STUFF is for types for which the GNAT Ada compiler
+    /* * GNAT_STUFF is for types for which the GNAT Ada compiler
        provides additional information.  */
+
     struct gnat_aux_type *gnat_stuff;
 
-    /* FLOATFORMAT is for TYPE_CODE_FLT.  It is a pointer to two
+    /* * FLOATFORMAT is for TYPE_CODE_FLT.  It is a pointer to two
        floatformat objects that describe the floating-point value
        that resides within the type.  The first is for big endian
        targets and the second is for little endian targets.  */
 
     const struct floatformat **floatformat;
 
-    /* For TYPE_CODE_FUNC types,  */
+    /* * For TYPE_CODE_FUNC types,  */
+
     struct func_type *func_stuff;
   } type_specific;
 };
 
-/* A ``struct type'' describes a particular instance of a type, with
+/* * A ``struct type'' describes a particular instance of a type, with
    some particular qualification.  */
+
 struct type
 {
-  /* Type that is a pointer to this type.
+  /* * Type that is a pointer to this type.
      NULL if no such pointer-to type is known yet.
      The debugger may add the address of such a type
      if it has to construct one later.  */
 
   struct type *pointer_type;
 
-  /* C++: also need a reference type.  */
+  /* * C++: also need a reference type.  */
 
   struct type *reference_type;
 
-  /* Variant chain.  This points to a type that differs from this one only
-     in qualifiers and length.  Currently, the possible qualifiers are
-     const, volatile, code-space, data-space, and address class.  The
-     length may differ only when one of the address class flags are set.
-     The variants are linked in a circular ring and share MAIN_TYPE.  */
+  /* * Variant chain.  This points to a type that differs from this
+     one only in qualifiers and length.  Currently, the possible
+     qualifiers are const, volatile, code-space, data-space, and
+     address class.  The length may differ only when one of the
+     address class flags are set.  The variants are linked in a
+     circular ring and share MAIN_TYPE.  */
+
   struct type *chain;
 
-  /* Flags specific to this instance of the type, indicating where
+  /* * Flags specific to this instance of the type, indicating where
      on the ring we are.
 
-     For TYPE_CODE_TYPEDEF the flags of the typedef type should be binary
-     or-ed with the target type, with a special case for address class and
-     space class.  For example if this typedef does not specify any new
-     qualifiers, TYPE_INSTANCE_FLAGS is 0 and the instance flags are
-     completely inherited from the target type.  No qualifiers can be cleared
-     by the typedef.  See also check_typedef.  */
+     For TYPE_CODE_TYPEDEF the flags of the typedef type should be
+     binary or-ed with the target type, with a special case for
+     address class and space class.  For example if this typedef does
+     not specify any new qualifiers, TYPE_INSTANCE_FLAGS is 0 and the
+     instance flags are completely inherited from the target type.  No
+     qualifiers can be cleared by the typedef.  See also
+     check_typedef.  */
   int instance_flags;
 
-  /* Length of storage for a value of this type.  This is what
-     sizeof(type) would return; use it for address arithmetic,
-     memory reads and writes, etc.  This size includes padding.  For
-     example, an i386 extended-precision floating point value really
-     only occupies ten bytes, but most ABI's declare its size to be
-     12 bytes, to preserve alignment.  A `struct type' representing
-     such a floating-point type would have a `length' value of 12,
-     even though the last two bytes are unused.
+  /* * Length of storage for a value of this type.  This is what
+     sizeof(type) would return; use it for address arithmetic, memory
+     reads and writes, etc.  This size includes padding.  For example,
+     an i386 extended-precision floating point value really only
+     occupies ten bytes, but most ABI's declare its size to be 12
+     bytes, to preserve alignment.  A `struct type' representing such
+     a floating-point type would have a `length' value of 12, even
+     though the last two bytes are unused.
 
      There's a bit of a host/target mess here, if you're concerned
      about machines whose bytes aren't eight bits long, or who don't
@@ -705,43 +754,47 @@ struct type
   
   unsigned length;
 
-  /* Core type, shared by a group of qualified types.  */
+  /* * Core type, shared by a group of qualified types.  */
+
   struct main_type *main_type;
 };
 
 #define	NULL_TYPE ((struct type *) 0)
 
-/* C++ language-specific information for TYPE_CODE_STRUCT and TYPE_CODE_UNION
-   nodes.  */
+/* * C++ language-specific information for TYPE_CODE_STRUCT and
+   TYPE_CODE_UNION nodes.  */
 
 struct cplus_struct_type
   {
-    /* Number of base classes this type derives from.  The baseclasses are
-       stored in the first N_BASECLASSES fields (i.e. the `fields' field of
-       the struct type).  I think only the `type' field of such a field has
-       any meaning.  */
+    /* * Number of base classes this type derives from.  The
+       baseclasses are stored in the first N_BASECLASSES fields
+       (i.e. the `fields' field of the struct type).  I think only the
+       `type' field of such a field has any meaning.  */
 
     short n_baseclasses;
 
-    /* Number of methods with unique names.  All overloaded methods with
-       the same name count only once.  */
+    /* * Number of methods with unique names.  All overloaded methods
+       with the same name count only once.  */
 
     short nfn_fields;
 
-    /* Number of template arguments.  */
+    /* * Number of template arguments.  */
+
     unsigned short n_template_arguments;
 
-    /* One if this struct is a dynamic class, as defined by the
+    /* * One if this struct is a dynamic class, as defined by the
        Itanium C++ ABI: if it requires a virtual table pointer,
        because it or any of its base classes have one or more virtual
        member functions or virtual base classes.  Minus one if not
        dynamic.  Zero if not yet computed.  */
+
     int is_dynamic : 2;
 
-    /* Non-zero if this type came from a Java CU.  */
+    /* * Non-zero if this type came from a Java CU.  */
+
     unsigned int is_java : 1;
 
-    /* For derived classes, the number of base classes is given by
+    /* * For derived classes, the number of base classes is given by
        n_baseclasses and virtual_field_bits is a bit vector containing
        one bit per base class.  If the base class is virtual, the
        corresponding bit will be set.
@@ -756,72 +809,75 @@ struct cplus_struct_type
 
     B_TYPE *virtual_field_bits;
 
-    /* For classes with private fields, the number of fields is given by
-       nfields and private_field_bits is a bit vector containing one bit
-       per field.
+    /* * For classes with private fields, the number of fields is
+       given by nfields and private_field_bits is a bit vector
+       containing one bit per field.
+
        If the field is private, the corresponding bit will be set.  */
 
     B_TYPE *private_field_bits;
 
-    /* For classes with protected fields, the number of fields is given by
-       nfields and protected_field_bits is a bit vector containing one bit
-       per field.
+    /* * For classes with protected fields, the number of fields is
+       given by nfields and protected_field_bits is a bit vector
+       containing one bit per field.
+
        If the field is private, the corresponding bit will be set.  */
 
     B_TYPE *protected_field_bits;
 
-    /* For classes with fields to be ignored, either this is optimized out
-       or this field has length 0.  */
+    /* * For classes with fields to be ignored, either this is
+       optimized out or this field has length 0.  */
 
     B_TYPE *ignore_field_bits;
 
-    /* For classes, structures, and unions, a description of each field,
-       which consists of an overloaded name, followed by the types of
-       arguments that the method expects, and then the name after it
-       has been renamed to make it distinct.
+    /* * For classes, structures, and unions, a description of each
+       field, which consists of an overloaded name, followed by the
+       types of arguments that the method expects, and then the name
+       after it has been renamed to make it distinct.
 
        fn_fieldlists points to an array of nfn_fields of these.  */
 
     struct fn_fieldlist
       {
 
-	/* The overloaded name.
+	/* * The overloaded name.
 	   This is generally allocated in the objfile's obstack.
 	   However stabsread.c sometimes uses malloc.  */
 
 	const char *name;
 
-	/* The number of methods with this name.  */
+	/* * The number of methods with this name.  */
 
 	int length;
 
-	/* The list of methods.  */
+	/* * The list of methods.  */
 
 	struct fn_field
 	  {
 
-	    /* If is_stub is clear, this is the mangled name which we can
-	       look up to find the address of the method (FIXME: it would
-	       be cleaner to have a pointer to the struct symbol here
-	       instead).  */
+	    /* * If is_stub is clear, this is the mangled name which
+	       we can look up to find the address of the method
+	       (FIXME: it would be cleaner to have a pointer to the
+	       struct symbol here instead).
 
-	    /* If is_stub is set, this is the portion of the mangled
+	       If is_stub is set, this is the portion of the mangled
 	       name which specifies the arguments.  For example, "ii",
 	       if there are two int arguments, or "" if there are no
-	       arguments.  See gdb_mangle_name for the conversion from this
-	       format to the one used if is_stub is clear.  */
+	       arguments.  See gdb_mangle_name for the conversion from
+	       this format to the one used if is_stub is clear.  */
 
 	    const char *physname;
 
-	    /* The function type for the method.
-	       (This comment used to say "The return value of the method",
-	       but that's wrong.  The function type 
-	       is expected here, i.e. something with TYPE_CODE_FUNC,
-	       and *not* the return-value type).  */
+	    /* * The function type for the method.
+	       
+	       (This comment used to say "The return value of the
+	       method", but that's wrong.  The function type is
+	       expected here, i.e. something with TYPE_CODE_FUNC, and
+	       *not* the return-value type).  */
 
 	    struct type *type;
 
-	    /* For virtual functions.
+	    /* * For virtual functions.
 	       First baseclass that defines this virtual function.  */
 
 	    struct type *fcontext;
@@ -840,18 +896,21 @@ struct cplus_struct_type
 	    unsigned int is_native:1;
 	    unsigned int is_artificial:1;
 
-	    /* A stub method only has some fields valid (but they are enough
-	       to reconstruct the rest of the fields).  */
+	    /* * A stub method only has some fields valid (but they
+	       are enough to reconstruct the rest of the fields).  */
+
 	    unsigned int is_stub:1;
 
-	    /* True if this function is a constructor, false
+	    /* * True if this function is a constructor, false
 	       otherwise.  */
+
 	    unsigned int is_constructor : 1;
 
-	    /* Unused.  */
+	    /* * Unused.  */
+
 	    unsigned int dummy:3;
 
-	    /* Index into that baseclass's virtual function table,
+	    /* * Index into that baseclass's virtual function table,
 	       minus 2; else if static: VOFFSET_STATIC; else: 0.  */
 
 	    unsigned int voffset:16;
@@ -864,68 +923,82 @@ struct cplus_struct_type
       }
      *fn_fieldlists;
 
-    /* typedefs defined inside this class.  TYPEDEF_FIELD points to an array of
-       TYPEDEF_FIELD_COUNT elements.  */
+    /* * typedefs defined inside this class.  typedef_field points to
+       an array of typedef_field_count elements.  */
+
     struct typedef_field
       {
-	/* Unqualified name to be prefixed by owning class qualified name.  */
+	/* * Unqualified name to be prefixed by owning class qualified
+	   name.  */
+
 	const char *name;
 
-	/* Type this typedef named NAME represents.  */
+	/* * Type this typedef named NAME represents.  */
+
 	struct type *type;
       }
     *typedef_field;
     unsigned typedef_field_count;
 
-    /* The template arguments.  This is an array with
+    /* * The template arguments.  This is an array with
        N_TEMPLATE_ARGUMENTS elements.  This is NULL for non-template
        classes.  */
+
     struct symbol **template_arguments;
   };
 
-/* Struct used to store conversion rankings.  */
+/* * Struct used to store conversion rankings.  */
+
 struct rank
   {
     short rank;
 
-    /* When two conversions are of the same type and therefore have the same
-       rank, subrank is used to differentiate the two.
-       Eg: Two derived-class-pointer to base-class-pointer conversions would
-       both have base pointer conversion rank, but the conversion with the
-       shorter distance to the ancestor is preferable.  'subrank' would be used
-       to reflect that.  */
+    /* * When two conversions are of the same type and therefore have
+       the same rank, subrank is used to differentiate the two.
+
+       Eg: Two derived-class-pointer to base-class-pointer conversions
+       would both have base pointer conversion rank, but the
+       conversion with the shorter distance to the ancestor is
+       preferable.  'subrank' would be used to reflect that.  */
+
     short subrank;
   };
 
-/* Struct used for ranking a function for overload resolution.  */
+/* * Struct used for ranking a function for overload resolution.  */
+
 struct badness_vector
   {
     int length;
     struct rank *rank;
   };
 
-/* GNAT Ada-specific information for various Ada types.  */
+/* * GNAT Ada-specific information for various Ada types.  */
+
 struct gnat_aux_type
   {
-    /* Parallel type used to encode information about dynamic types
+    /* * Parallel type used to encode information about dynamic types
        used in Ada (such as variant records, variable-size array,
        etc).  */
     struct type* descriptive_type;
   };
 
-/* For TYPE_CODE_FUNC types,  */
+/* * For TYPE_CODE_FUNC types.  */
+
 struct func_type
   {
-    /* The calling convention for targets supporting multiple ABIs.  Right now
-       this is only fetched from the Dwarf-2 DW_AT_calling_convention
-       attribute.  */
+    /* * The calling convention for targets supporting multiple ABIs.
+       Right now this is only fetched from the Dwarf-2
+       DW_AT_calling_convention attribute.  */
+
     unsigned calling_convention;
 
-    /* Only those DW_TAG_GNU_call_site's in this function that have
-       DW_AT_GNU_tail_call set are linked in this list.  Function without its
-       tail call list complete (DW_AT_GNU_all_tail_call_sites or its superset
+    /* * Only those DW_TAG_GNU_call_site's in this function that have
+       DW_AT_GNU_tail_call set are linked in this list.  Function
+       without its tail call list complete
+       (DW_AT_GNU_all_tail_call_sites or its superset
        DW_AT_GNU_all_call_sites) has TAIL_CALL_LIST NULL, even if some
        DW_TAG_GNU_call_site's exist in such function. */
+
     struct call_site *tail_call_list;
   };
 
@@ -933,83 +1006,99 @@ struct func_type
 
 enum call_site_parameter_kind
 {
-  /* Use field call_site_parameter.u.dwarf_reg.  */
+  /* * Use field call_site_parameter.u.dwarf_reg.  */
   CALL_SITE_PARAMETER_DWARF_REG,
 
-  /* Use field call_site_parameter.u.fb_offset.  */
+  /* * Use field call_site_parameter.u.fb_offset.  */
   CALL_SITE_PARAMETER_FB_OFFSET,
 
-  /* Use field call_site_parameter.u.param_offset.  */
+  /* * Use field call_site_parameter.u.param_offset.  */
   CALL_SITE_PARAMETER_PARAM_OFFSET
 };
 
-/* A place where a function gets called from, represented by
-   DW_TAG_GNU_call_site.  It can be looked up from symtab->call_site_htab.  */
+/* * A place where a function gets called from, represented by
+   DW_TAG_GNU_call_site.  It can be looked up from
+   symtab->call_site_htab.  */
 
 struct call_site
   {
-    /* Address of the first instruction after this call.  It must be the first
-       field as we overload core_addr_hash and core_addr_eq for it.  */
+    /* * Address of the first instruction after this call.  It must be
+       the first field as we overload core_addr_hash and core_addr_eq
+       for it.  */
+
     CORE_ADDR pc;
 
-    /* List successor with head in FUNC_TYPE.TAIL_CALL_LIST.  */
+    /* * List successor with head in FUNC_TYPE.TAIL_CALL_LIST.  */
+
     struct call_site *tail_call_next;
 
-    /* Describe DW_AT_GNU_call_site_target.  Missing attribute uses
+    /* * Describe DW_AT_GNU_call_site_target.  Missing attribute uses
        FIELD_LOC_KIND_DWARF_BLOCK with FIELD_DWARF_BLOCK == NULL.  */
+
     struct
       {
 	union field_location loc;
 
-	/* Discriminant for union field_location.  */
+	/* * Discriminant for union field_location.  */
+
 	ENUM_BITFIELD(field_loc_kind) loc_kind : 3;
       }
     target;
 
-    /* Size of the PARAMETER array.  */
+    /* * Size of the PARAMETER array.  */
+
     unsigned parameter_count;
 
-    /* CU of the function where the call is located.  It gets used for DWARF
-       blocks execution in the parameter array below.  */
+    /* * CU of the function where the call is located.  It gets used
+       for DWARF blocks execution in the parameter array below.  */
+
     struct dwarf2_per_cu_data *per_cu;
 
-    /* Describe DW_TAG_GNU_call_site's DW_TAG_formal_parameter.  */
+    /* * Describe DW_TAG_GNU_call_site's DW_TAG_formal_parameter.  */
+
     struct call_site_parameter
       {
 	ENUM_BITFIELD (call_site_parameter_kind) kind : 2;
 
 	union call_site_parameter_u
 	  {
-	    /* DW_TAG_formal_parameter's DW_AT_location's DW_OP_regX as DWARF
-	       register number, for register passed parameters.  */
+	    /* * DW_TAG_formal_parameter's DW_AT_location's DW_OP_regX
+	       as DWARF register number, for register passed
+	       parameters.  */
+
 	    int dwarf_reg;
 
-	    /* Offset from the callee's frame base, for stack passed parameters.
-	       This equals offset from the caller's stack pointer.  */
+	    /* * Offset from the callee's frame base, for stack passed
+	       parameters.  This equals offset from the caller's stack
+	       pointer.  */
+
 	    CORE_ADDR fb_offset;
 
-	    /* Offset relative to the start of this PER_CU to
-	       DW_TAG_formal_parameter which is referenced by both caller and
-	       the callee.  */
+	    /* * Offset relative to the start of this PER_CU to
+	       DW_TAG_formal_parameter which is referenced by both
+	       caller and the callee.  */
+
 	    cu_offset param_offset;
 	  }
 	u;
 
-	/* DW_TAG_formal_parameter's DW_AT_GNU_call_site_value.  It is never
-	   NULL.  */
+	/* * DW_TAG_formal_parameter's DW_AT_GNU_call_site_value.  It
+	   is never NULL.  */
+
 	const gdb_byte *value;
 	size_t value_size;
 
-	/* DW_TAG_formal_parameter's DW_AT_GNU_call_site_data_value.  It may be
-	   NULL if not provided by DWARF.  */
+	/* * DW_TAG_formal_parameter's DW_AT_GNU_call_site_data_value.
+	   It may be NULL if not provided by DWARF.  */
+
 	const gdb_byte *data_value;
 	size_t data_value_size;
       }
     parameter[1];
   };
 
-/* The default value of TYPE_CPLUS_SPECIFIC(T) points to the
-   this shared static structure.  */
+/* * The default value of TYPE_CPLUS_SPECIFIC(T) points to this shared
+   static structure.  */
 
 extern const struct cplus_struct_type cplus_struct_default;
 
@@ -1034,7 +1123,7 @@ extern void allocate_gnat_aux_type (struct type *);
   (TYPE_SPECIFIC_FIELD (type) = TYPE_SPECIFIC_GNAT_STUFF, \
    TYPE_GNAT_SPECIFIC (type) = (struct gnat_aux_type *) &gnat_aux_default)
 #define ALLOCATE_GNAT_AUX_TYPE(type) allocate_gnat_aux_type (type)
-/* A macro that returns non-zero if the type-specific data should be
+/* * A macro that returns non-zero if the type-specific data should be
    read as "gnat-stuff".  */
 #define HAVE_GNAT_AUX_INFO(type) \
   (TYPE_SPECIFIC_FIELD (type) == TYPE_SPECIFIC_GNAT_STUFF)
@@ -1053,12 +1142,12 @@ extern void allocate_gnat_aux_type (struct type *);
 #define TYPE_POINTER_TYPE(thistype) (thistype)->pointer_type
 #define TYPE_REFERENCE_TYPE(thistype) (thistype)->reference_type
 #define TYPE_CHAIN(thistype) (thistype)->chain
-/* Note that if thistype is a TYPEDEF type, you have to call check_typedef.
+/* * Note that if thistype is a TYPEDEF type, you have to call check_typedef.
    But check_typedef does set the TYPE_LENGTH of the TYPEDEF type,
    so you only have to call check_typedef once.  Since allocate_value
    calls check_typedef, TYPE_LENGTH (VALUE_TYPE (X)) is safe.  */
 #define TYPE_LENGTH(thistype) (thistype)->length
-/* Note that TYPE_CODE can be TYPE_CODE_TYPEDEF, so if you want the real
+/* * Note that TYPE_CODE can be TYPE_CODE_TYPEDEF, so if you want the real
    type, you need to do TYPE_CODE (check_type (this_type)).  */
 #define TYPE_CODE(thistype) TYPE_MAIN_TYPE(thistype)->code
 #define TYPE_NFIELDS(thistype) TYPE_MAIN_TYPE(thistype)->nfields
@@ -1248,13 +1337,15 @@ extern void allocate_gnat_aux_type (struct type *);
        || TYPE_NFN_FIELDS (thistype) == 0) \
    && (TYPE_STUB (thistype) || !TYPE_STUB_SUPPORTED (thistype)))
 
-/* A helper macro that returns the name of a type or "unnamed type" if the type
-   has no name.  */
+/* * A helper macro that returns the name of a type or "unnamed type"
+   if the type has no name.  */
+
 #define TYPE_SAFE_NAME(type) \
   (TYPE_NAME (type) ? TYPE_NAME (type) : _("<unnamed type>"))
 
-/* A helper macro that returns the name of an error type.  If the type
-   has a name, it is used; otherwise, a default is used.  */
+/* * A helper macro that returns the name of an error type.  If the
+   type has a name, it is used; otherwise, a default is used.  */
+
 #define TYPE_ERROR_NAME(type) \
   (TYPE_NAME (type) ? TYPE_NAME (type) : _("<error type>"))
 
@@ -1314,11 +1405,11 @@ struct builtin_type
 
   /* Pointer types.  */
 
-  /* `pointer to data' type.  Some target platforms use an implicitly
+  /* * `pointer to data' type.  Some target platforms use an implicitly
      {sign,zero} -extended 32-bit ABI pointer on a 64-bit ISA.  */
   struct type *builtin_data_ptr;
 
-  /* `pointer to function (returning void)' type.  Harvard
+  /* * `pointer to function (returning void)' type.  Harvard
      architectures mean that ABI function and code pointers are not
      interconvertible.  Similarly, since ANSI, C standards have
      explicitly said that pointers to functions and pointers to data
@@ -1326,24 +1417,26 @@ struct builtin_type
      pointer to void * and back, and expect to get the same value.
      However, all function pointer types are interconvertible, so void
      (*) () can server as a generic function pointer.  */
+
   struct type *builtin_func_ptr;
 
-  /* `function returning pointer to function (returning void)' type.
+  /* * `function returning pointer to function (returning void)' type.
      The final void return type is not significant for it.  */
-  struct type *builtin_func_func;
 
+  struct type *builtin_func_func;
 
   /* Special-purpose types.  */
 
-  /* This type is used to represent a GDB internal function.  */
+  /* * This type is used to represent a GDB internal function.  */
+
   struct type *internal_fn;
 };
 
-/* Return the type table for the specified architecture.  */
-extern const struct builtin_type *builtin_type (struct gdbarch *gdbarch);
+/* * Return the type table for the specified architecture.  */
 
+extern const struct builtin_type *builtin_type (struct gdbarch *gdbarch);
 
-/* Per-objfile types used by symbol readers.  */
+/* * Per-objfile types used by symbol readers.  */
 
 struct objfile_type
 {
@@ -1364,13 +1457,14 @@ struct objfile_type
   struct type *builtin_double;
   struct type *builtin_long_double;
 
-  /* This type is used to represent symbol addresses.  */
+  /* * This type is used to represent symbol addresses.  */
   struct type *builtin_core_addr;
 
-  /* This type represents a type that was unrecognized in symbol read-in.  */
+  /* * This type represents a type that was unrecognized in symbol
+     read-in.  */
   struct type *builtin_error;
 
-  /* Types used for symbols with no debug information.  */
+  /* * Types used for symbols with no debug information.  */
   struct type *nodebug_text_symbol;
   struct type *nodebug_text_gnu_ifunc_symbol;
   struct type *nodebug_got_plt_symbol;
@@ -1379,9 +1473,9 @@ struct objfile_type
   struct type *nodebug_tls_symbol;
 };
 
-/* Return the type table for the specified objfile.  */
-extern const struct objfile_type *objfile_type (struct objfile *objfile);
+/* * Return the type table for the specified objfile.  */
 
+extern const struct objfile_type *objfile_type (struct objfile *objfile);
  
 /* Explicit floating-point formats.  See "floatformat.h".  */
 extern const struct floatformat *floatformats_ieee_half[BFD_ENDIAN_UNKNOWN];
@@ -1398,14 +1492,15 @@ extern const struct floatformat *floatformats_vax_d[BFD_ENDIAN_UNKNOWN];
 extern const struct floatformat *floatformats_ibm_long_double[BFD_ENDIAN_UNKNOWN];
 
 
-/* Allocate space for storing data associated with a particular type.
-   We ensure that the space is allocated using the same mechanism that
-   was used to allocate the space for the type structure itself.  I.e.
-   if the type is on an objfile's objfile_obstack, then the space for data
-   associated with that type will also be allocated on the objfile_obstack.
-   If the type is not associated with any particular objfile (such as
-   builtin types), then the data space will be allocated with xmalloc,
-   the same as for the type structure.  */
+/* * Allocate space for storing data associated with a particular
+   type.  We ensure that the space is allocated using the same
+   mechanism that was used to allocate the space for the type
+   structure itself.  I.e.  if the type is on an objfile's
+   objfile_obstack, then the space for data associated with that type
+   will also be allocated on the objfile_obstack.  If the type is not
+   associated with any particular objfile (such as builtin types),
+   then the data space will be allocated with xmalloc, the same as for
+   the type structure.  */
 
 #define TYPE_ALLOC(t,size)  \
    (TYPE_OBJFILE_OWNED (t) \
@@ -1418,24 +1513,28 @@ extern const struct floatformat *floatformats_ibm_long_double[BFD_ENDIAN_UNKNOWN
 	      0, size)  \
     : xzalloc (size))
 
-/* Use alloc_type to allocate a type owned by an objfile.
-   Use alloc_type_arch to allocate a type owned by an architecture.
-   Use alloc_type_copy to allocate a type with the same owner as a
-   pre-existing template type, no matter whether objfile or gdbarch.  */
+/* Use alloc_type to allocate a type owned by an objfile.  Use
+   alloc_type_arch to allocate a type owned by an architecture.  Use
+   alloc_type_copy to allocate a type with the same owner as a
+   pre-existing template type, no matter whether objfile or
+   gdbarch.  */
 extern struct type *alloc_type (struct objfile *);
 extern struct type *alloc_type_arch (struct gdbarch *);
 extern struct type *alloc_type_copy (const struct type *);
 
-/* Return the type's architecture.  For types owned by an architecture,
-   that architecture is returned.  For types owned by an objfile, that
-   objfile's architecture is returned.  */
+/* * Return the type's architecture.  For types owned by an
+   architecture, that architecture is returned.  For types owned by an
+   objfile, that objfile's architecture is returned.  */
+
 extern struct gdbarch *get_type_arch (const struct type *);
 
-/* This returns the target type (or NULL) of TYPE, also skipping
+/* * This returns the target type (or NULL) of TYPE, also skipping
    past typedefs.  */
+
 extern struct type *get_target_type (struct type *type);
 
-/* Helper function to construct objfile-owned types.  */
+/* * Helper function to construct objfile-owned types.  */
+
 extern struct type *init_type (enum type_code, int, int, const char *,
 			       struct objfile *);
 
@@ -1590,46 +1689,47 @@ extern int is_unique_ancestor (struct type *, struct value *);
 
 #define LENGTH_MATCH(bv) ((bv)->rank[0])
 
-/* Badness if parameter list length doesn't match arg list length.  */
+/* * Badness if parameter list length doesn't match arg list length.  */
 extern const struct rank LENGTH_MISMATCH_BADNESS;
 
-/* Dummy badness value for nonexistent parameter positions.  */
+/* * Dummy badness value for nonexistent parameter positions.  */
 extern const struct rank TOO_FEW_PARAMS_BADNESS;
-/* Badness if no conversion among types.  */
+/* * Badness if no conversion among types.  */
 extern const struct rank INCOMPATIBLE_TYPE_BADNESS;
 
-/* Badness of an exact match.  */
+/* * Badness of an exact match.  */
 extern const struct rank EXACT_MATCH_BADNESS;
 
-/* Badness of integral promotion.  */
+/* * Badness of integral promotion.  */
 extern const struct rank INTEGER_PROMOTION_BADNESS;
-/* Badness of floating promotion.  */
+/* * Badness of floating promotion.  */
 extern const struct rank FLOAT_PROMOTION_BADNESS;
-/* Badness of converting a derived class pointer
+/* * Badness of converting a derived class pointer
    to a base class pointer.  */
 extern const struct rank BASE_PTR_CONVERSION_BADNESS;
-/* Badness of integral conversion.  */
+/* * Badness of integral conversion.  */
 extern const struct rank INTEGER_CONVERSION_BADNESS;
-/* Badness of floating conversion.  */
+/* * Badness of floating conversion.  */
 extern const struct rank FLOAT_CONVERSION_BADNESS;
-/* Badness of integer<->floating conversions.  */
+/* * Badness of integer<->floating conversions.  */
 extern const struct rank INT_FLOAT_CONVERSION_BADNESS;
-/* Badness of conversion of pointer to void pointer.  */
+/* * Badness of conversion of pointer to void pointer.  */
 extern const struct rank VOID_PTR_CONVERSION_BADNESS;
-/* Badness of conversion to boolean.  */
+/* * Badness of conversion to boolean.  */
 extern const struct rank BOOL_CONVERSION_BADNESS;
-/* Badness of converting derived to base class.  */
+/* * Badness of converting derived to base class.  */
 extern const struct rank BASE_CONVERSION_BADNESS;
-/* Badness of converting from non-reference to reference.  */
+/* * Badness of converting from non-reference to reference.  */
 extern const struct rank REFERENCE_CONVERSION_BADNESS;
-/* Badness of converting integer 0 to NULL pointer.  */
+/* * Badness of converting integer 0 to NULL pointer.  */
 extern const struct rank NULL_POINTER_CONVERSION;
 
 /* Non-standard conversions allowed by the debugger */
-/* Converting a pointer to an int is usually OK.  */
+
+/* * Converting a pointer to an int is usually OK.  */
 extern const struct rank NS_POINTER_CONVERSION_BADNESS;
 
-/* Badness of converting a (non-zero) integer constant
+/* * Badness of converting a (non-zero) integer constant
    to a pointer.  */
 extern const struct rank NS_INTEGER_POINTER_CONVERSION_BADNESS;