Document new Python and Guile constants

This documents the new Python and Guile constants introduced earlier
in this series.

Approved-By: Eli Zaretskii <eliz@gnu.org>

3 files changed, 74 insertions, 4 deletions

diff --git a/gdb/NEWS b/gdb/NEWS
index bab300e36b8..2638b3e0d9c 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -108,6 +108,11 @@ show remote thread-options-packet
      object, these will be stored in the object's new
      InferiorThread.__dict__ attribute.
 
+  ** New constants gdb.SYMBOL_TYPE_DOMAIN, gdb.SYMBOL_FUNCTION_DOMAIN,
+     and gdb.SEARCH_*_DOMAIN corresponding to all the existing symbol
+     domains.  Symbol lookup can now search in multiple domains at
+     once, and can also narrowly search for just a type or function.
+
 * Debugger Adapter Protocol changes
 
   ** GDB now emits the "process" event.
@@ -121,6 +126,13 @@ show remote thread-options-packet
   ** The "set debug dap-log-file" command is now documented.  This
      command was available in GDB 14 but not documented.
 
+* Guile API
+
+  ** New constants SYMBOL_TYPE_DOMAIN, SYMBOL_FUNCTION_DOMAIN, and
+     SEARCH_*_DOMAIN corresponding to all the existing symbol domains.
+     Symbol lookup can now search in multiple domains at once, and can
+     also narrowly search for just a type or function.
+
 * New remote packets
 
 New stop reason: clone
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 271b672fdc6..7326186941d 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -2802,8 +2802,24 @@ in the symbol information or in @value{GDBN}'s handling of symbols.
 This domain contains variables, function names, typedef names and enum
 type values.
 
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains functions.
+
+@item SYMBOL_TYPE_DOMAIN
+This domain contains types.  In a C-like language, types using a tag
+(the name appearing after a @code{struct}, @code{union}, or
+@code{enum} keyword) will not appear here; in other languages, all
+types are in this domain.
+
 @item SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
+This domain holds struct, union and enum tag names.  This domain is
+only used for C-like languages.  For example, in this code:
+@smallexample
+struct type_one @{ int x; @};
+typedef struct type_one type_two;
+@end smallexample
+Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but
+@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}.
 
 @item SYMBOL_LABEL_DOMAIN
 This domain contains names of labels (for gotos).
@@ -2822,6 +2838,15 @@ This domain contains all types.
 The available address class categories in @code{<gdb:symbol>} are represented
 as constants in the @code{gdb} module:
 
+When searching for a symbol, the desired domain constant can be passed
+verbatim to the lookup function.
+
+For more complex searches, there is a corresponding set of constants,
+each named after one of the preceding constants, but with the
+@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example,
+@code{SEARCH_LABEL_DOMAIN}.  These may be or'd together to form a
+search constant.
+
 @vtable @code
 @item SYMBOL_LOC_UNDEF
 If this is returned by address class, it indicates an error either in
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 71431878dd3..ece9038844c 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -6214,12 +6214,29 @@ in the symbol information or in @value{GDBN}'s handling of symbols.
 
 @vindex SYMBOL_VAR_DOMAIN
 @item gdb.SYMBOL_VAR_DOMAIN
-This domain contains variables, function names, typedef names and enum
-type values.
+This domain contains variables.
+
+@vindex SYMBOL_FUNCTION_DOMAIN
+@item gdb.SYMBOL_FUNCTION_DOMAIN
+This domain contains functions.
+
+@vindex SYMBOL_TYPE_DOMAIN
+@item gdb.SYMBOL_TYPE_DOMAIN
+This domain contains types.  In a C-like language, types using a tag
+(the name appearing after a @code{struct}, @code{union}, or
+@code{enum} keyword) will not appear here; in other languages, all
+types are in this domain.
 
 @vindex SYMBOL_STRUCT_DOMAIN
 @item gdb.SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
+This domain holds struct, union and enum tag names.  This domain is
+only used for C-like languages.  For example, in this code:
+@smallexample
+struct type_one @{ int x; @};
+typedef struct type_one type_two;
+@end smallexample
+Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but
+@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}.
 
 @vindex SYMBOL_LABEL_DOMAIN
 @item gdb.SYMBOL_LABEL_DOMAIN
@@ -6234,6 +6251,22 @@ This domain contains names of Fortran module types.
 This domain contains names of Fortran common blocks.
 @end vtable
 
+When searching for a symbol, the desired domain constant can be passed
+verbatim to the lookup function.  For example:
+@smallexample
+symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN)
+@end smallexample
+
+For more complex searches, there is a corresponding set of constants,
+each named after one of the preceding constants, but with the
+@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example,
+@code{SEARCH_LABEL_DOMAIN}.  These may be or'd together to form a
+search constant, e.g.:
+@smallexample
+symbol = gdb.lookup_symbol ("name",
+                            domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN)
+@end smallexample
+
 The available address class categories in @code{gdb.Symbol} are represented
 as constants in the @code{gdb} module: