[PATCH v2] gdbtypes: improve documentation of composite type helpers

[Matthieu Longo <matthieu.longo@arm.com>]

Document how arch_composite_type handles a null NAME, and clarify the
semantics of an empty field name for the append_composite_type* helpers.

Suggested-By: Simon Marchi <simark@simark.ca>
---
 gdb/gdbtypes.c | 12 ++++--------
 gdb/gdbtypes.h | 30 ++++++++++++++++++++++++++----
 2 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/gdb/gdbtypes.c b/gdb/gdbtypes.c
index 4b6c01910f4..e0c25c58d83 100644
--- a/gdb/gdbtypes.c
+++ b/gdb/gdbtypes.c
@@ -5412,8 +5412,7 @@ append_flags_type_flag (struct type *type, int bitpos, const char *name)
 			   name);
 }
 
-/* Allocate a TYPE_CODE_STRUCT or TYPE_CODE_UNION type structure (as
-   specified by CODE) associated with GDBARCH.  NAME is the type name.  */
+/* See gdbtypes.h.  */
 
 struct type *
 arch_composite_type (struct gdbarch *gdbarch, const char *name,
@@ -5428,9 +5427,7 @@ arch_composite_type (struct gdbarch *gdbarch, const char *name,
   return t;
 }
 
-/* Add new field with name NAME and type FIELD to composite type T.
-   Do not set the field's position or adjust the type's length;
-   the caller should do so.  Return the new field.  */
+/* See gdbtypes.h.  */
 
 struct field *
 append_composite_type_field_raw (struct type *t, const char *name,
@@ -5448,8 +5445,7 @@ append_composite_type_field_raw (struct type *t, const char *name,
   return f;
 }
 
-/* Add new field with name NAME and type FIELD to composite type T.
-   ALIGNMENT (if non-zero) specifies the minimum field alignment.  */
+/* See gdbtypes.h.  */
 
 void
 append_composite_type_field_aligned (struct type *t, const char *name,
@@ -5489,7 +5485,7 @@ append_composite_type_field_aligned (struct type *t, const char *name,
     }
 }
 
-/* Add new field with name NAME and type FIELD to composite type T.  */
+/* See gdbtypes.h.  */
 
 void
 append_composite_type_field (struct type *t, const char *name,
diff --git a/gdb/gdbtypes.h b/gdb/gdbtypes.h
index dd2d24fa8e2..f7853430d64 100644
--- a/gdb/gdbtypes.h
+++ b/gdb/gdbtypes.h
@@ -2431,20 +2431,42 @@ extern struct type *init_pointer_type (type_allocator &alloc, int bit,
 extern struct type *init_fixed_point_type (type_allocator &, int, int,
 					   const char *);
 
-/* Helper functions to construct a struct or record type.  An
-   initially empty type is created using arch_composite_type().
-   Fields are then added using append_composite_type_field*().  A union
-   type has its size set to the largest field.  A struct type has each
+/* Helper functions to construct a struct or record type.  An initially empty
+   type is created using arch_composite_type().  Fields are then added using
+   append_composite_type_field*().
+   A union type has its size set to the largest field.  A struct type has each
    field packed against the previous.  */
 
+/* Allocate a TYPE_CODE_STRUCT or TYPE_CODE_UNION type structure (as
+   specified by CODE) associated with GDBARCH.  NAME is the type name.
+   If NAME is nullptr, the type is anonymous.  */
+
 extern struct type *arch_composite_type (struct gdbarch *gdbarch,
 					 const char *name, enum type_code code);
+
+/* Add a new field named NAME with type FIELD to composite type T.
+   If NAME is an empty string, the field represents an anonymous struct or
+   union whose fields are visible directly in the parent scope.  */
+
 extern void append_composite_type_field (struct type *t, const char *name,
 					 struct type *field);
+
+/* Add a new field named NAME with type FIELD to composite type T.
+   ALIGNMENT (if non-zero) specifies the minimum field alignment.
+   If NAME is an empty string, the field represents an anonymous struct or
+   union whose fields are visible directly in the parent scope.   */
+
 extern void append_composite_type_field_aligned (struct type *t,
 						 const char *name,
 						 struct type *field,
 						 int alignment);
+
+/* Add a new field named NAME with type FIELD to composite type T.
+   This function does not set the field's position or adjust the length of T;
+   the caller is responsible for doing so.  If NAME is an empty string, the
+   field represents an anonymous struct or union whose fields are visible
+   directly in the parent scope.  Return the newly added field.  */
+
 struct field *append_composite_type_field_raw (struct type *t, const char *name,
 					       struct type *field);
 
-- 
2.55.0