[binutils-gdb] Add comments to dwarf2/abbrev-cache.h

[Tom Tromey <tromey@sourceware.org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=3c8184c43d179e03473805f4f82cbbb3eba751f4

commit 3c8184c43d179e03473805f4f82cbbb3eba751f4
Author: Tom Tromey <tom@tromey.com>
Date:   Sat Apr 16 13:58:34 2022 -0600

    Add comments to dwarf2/abbrev-cache.h
    
    This patch started when I noticed that the unordered_set include
    wasn't needed in abbrev-cache.h.  (That was probably leftover from
    some earlier implementation of the class.)  Then, I noticed that the
    class itself was under-commented.  This patch fixes both issues.

Diff:
---
 gdb/dwarf2/abbrev-cache.h | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/gdb/dwarf2/abbrev-cache.h b/gdb/dwarf2/abbrev-cache.h
index 7af28cd8181..d729eb9dd1b 100644
--- a/gdb/dwarf2/abbrev-cache.h
+++ b/gdb/dwarf2/abbrev-cache.h
@@ -21,15 +21,18 @@
 #define GDB_DWARF2_ABBREV_CACHE_H
 
 #include "dwarf2/abbrev.h"
-#include <unordered_set>
 #include "gdbtypes.h"
 
+/* An abbrev cache holds abbrev tables for easier reuse.  */
 class abbrev_cache
 {
 public:
   abbrev_cache ();
   DISABLE_COPY_AND_ASSIGN (abbrev_cache);
 
+  /* Find an abbrev table coming from the abbrev section SECTION at
+     offset OFFSET.  Return the table, or nullptr if it has not yet
+     been registered.  */
   abbrev_table *find (struct dwarf2_section_info *section, sect_offset offset)
   {
     search_key key = { section, offset };
@@ -38,6 +41,11 @@ public:
 						 to_underlying (offset));
   }
 
+  /* Add TABLE to this cache.  Ownership of TABLE is transferred to
+     the cache.  Note that a table at a given section+offset may only
+     be registered once -- a violation of this will cause an assert.
+     To avoid this, call the 'find' method first, to see if the table
+     has already been read.  */
   void add (abbrev_table_up table);
 
 private: