[binutils-gdb] Add/tweak intro comments of struct breakpoint and several subclasses

[Pedro Alves <palves@sourceware.org>]

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

commit 9a71ed14cb3c28238a12f19847a9f4f22ca20fd2
Author: Pedro Alves <pedro@palves.net>
Date:   Mon May 16 15:24:41 2022 +0100

    Add/tweak intro comments of struct breakpoint and several subclasses
    
    This tweaks the intro comments of the following classes:
    
     internal_breakpoint
     momentary_breakpoint
     breakpoint
     base_breakpoint
     watchpoint
     catchpoint
    
    Change-Id: If6b31f51ebbb81705fbe5b8435f60ab2c88a98c8

Diff:
---
 gdb/breakpoint.c | 12 ++++++++++--
 gdb/breakpoint.h | 13 +++++++------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index b6e31836df1..0c3946cbc36 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -271,7 +271,10 @@ struct ordinary_breakpoint : public base_breakpoint
   void print_recreate (struct ui_file *fp) const override;
 };
 
-/* Internal breakpoints.  */
+/* Internal breakpoints.  These typically have a lifetime the same as
+   the program, and they end up installed on the breakpoint chain with
+   a negative breakpoint number.  They're visible in "maint info
+   breakpoints", but not "info breakpoints".  */
 struct internal_breakpoint : public base_breakpoint
 {
   internal_breakpoint (struct gdbarch *gdbarch,
@@ -294,7 +297,12 @@ struct internal_breakpoint : public base_breakpoint
   void print_mention () const override;
 };
 
-/* Momentary breakpoints.  */
+/* Momentary breakpoints.  These typically have a lifetime of some run
+   control command only, are always thread-specific, and have 0 for
+   breakpoint number.  I.e., there can be many momentary breakpoints
+   on the breakpoint chain and they all same the same number (zero).
+   They're visible in "maint info breakpoints", but not "info
+   breakpoints".  */
 struct momentary_breakpoint : public base_breakpoint
 {
   using base_breakpoint::base_breakpoint;
diff --git a/gdb/breakpoint.h b/gdb/breakpoint.h
index 807c97a5bed..8735396e8d4 100644
--- a/gdb/breakpoint.h
+++ b/gdb/breakpoint.h
@@ -616,7 +616,7 @@ using bp_location_range = next_range<bp_location>;
    useful for a hack I had to put in; I'm going to leave it in because
    I can see how there might be times when it would indeed be useful */
 
-/* This is for all kinds of breakpoints.  */
+/* Abstract base class representing all kinds of breakpoints.  */
 
 struct breakpoint
 {
@@ -846,9 +846,9 @@ protected:
   void print_recreate_thread (struct ui_file *fp) const;
 };
 
-/* The structure to be inherit by all kinds of breakpoints (real
-   breakpoints, i.e., user "break" breakpoints, internal and momentary
-   breakpoints, etc.).  */
+/* Abstract base class representing code breakpoints.  User "break"
+   breakpoints, internal and momentary breakpoints, etc.  IOW, any
+   kind of breakpoint whose locations are created from SALs.  */
 struct base_breakpoint : public breakpoint
 {
   using breakpoint::breakpoint;
@@ -887,7 +887,8 @@ struct base_breakpoint : public breakpoint
 	struct program_space *search_pspace) override;
 };
 
-/* An instance of this type is used to represent a watchpoint.  */
+/* An instance of this type is used to represent a watchpoint,
+   a.k.a. a data breakpoint.  */
 
 struct watchpoint : public breakpoint
 {
@@ -1022,7 +1023,7 @@ struct tracepoint : public base_breakpoint
   int static_trace_marker_id_idx = 0;
 };
 
-/* The base class for catchpoints.  */
+/* The abstract base class for catchpoints.  */
 
 struct catchpoint : public breakpoint
 {