From: Tom Tromey <tromey@adacore.com>
Date: Fri, 30 Aug 2024 17:32:20 +0000 (-0600)
Subject: Improve comments in dwarf2/parent-map.h
X-Git-Tag: gdb-16-branchpoint~1000
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=82d6a9e5b4bfb313a8e7ce0ad6033fe78a147c00;p=thirdparty%2Fbinutils-gdb.git

Improve comments in dwarf2/parent-map.h

I noticed that the comments for class parent_map aren't very clear.
This patch attempts to fix this, and also clarifies a point on
parent_map_map::add_map.

Approved-By: Simon Marchi <simon.marchi@efficios.com>
---

diff --git a/gdb/dwarf2/parent-map.h b/gdb/dwarf2/parent-map.h
index 5a94bd9beff..5307d4df45b 100644
--- a/gdb/dwarf2/parent-map.h
+++ b/gdb/dwarf2/parent-map.h
@@ -32,9 +32,31 @@ class cooked_index_entry;
    The generated DWARF can sometimes have the declaration for a method
    in a class (or perhaps namespace) scope, with the definition
    appearing outside this scope... just one of the many bad things
-   about DWARF.  In order to handle this situation, we defer certain
-   entries until the end of scanning, at which point we'll know the
-   containing context of all the DIEs that we might have scanned.  */
+   about DWARF.
+
+   For example, a program like this:
+
+   struct X { int method (); };
+   int X::method () { return 23; }
+
+   ... ends up with DWARF like:
+
+    <1><2e>: Abbrev Number: 2 (DW_TAG_structure_type)
+       <2f>   DW_AT_name        : X
+    ...
+    <2><39>: Abbrev Number: 3 (DW_TAG_subprogram)
+       <3a>   DW_AT_external    : 1
+       <3a>   DW_AT_name        : (indirect string, offset: 0xf): method
+    ...
+    <1><66>: Abbrev Number: 8 (DW_TAG_subprogram)
+       <67>   DW_AT_specification: <0x39>
+
+    Here, the name of DIE 0x66 can't be determined without knowing the
+    parent of DIE 0x39.
+
+    In order to handle this situation, we defer certain entries until
+    the end of scanning, at which point we'll know the containing
+    context of all the DIEs that we might have scanned.  */
 class parent_map
 {
 public:
@@ -99,7 +121,8 @@ public:
 
   DISABLE_COPY_AND_ASSIGN (parent_map_map);
 
-  /* Add a parent_map to this map.  */
+  /* Add a parent_map to this map.  Note that a copy of MAP is made --
+     modifications to MAP after this call will have no effect.  */
   void add_map (const parent_map &map)
   {
     m_maps.push_back (map.to_fixed (&m_storage));