gdb/guile: generate general description string for parameters

This commit builds on the previous one, and auto-generates a general
description string for parameters defined via the Guile API.  This
brings the Guile API closer inline with the Python API.  It is worth
reading the previous commit to see some motivating examples.

This commit updates get_doc_string in guile/scm-param.c to allow for
the generation of a general description string.  Then in
gdbscm_make_parameter, if '#:doc' was not given, get_doc_string is
used to generate a suitable default.

This does invalidate (and so the commit removes) this comment that was
in gdbscm_make_parameter:

  /* If doc is NULL, leave it NULL.  See add_setshow_cmd_full.  */

First, Python already does exactly what I'm proposing here, and has
done for a while, with no issues reported.  And second, I've gone and
read add_setshow_cmd_full, and some of the functions it calls, and can
see no reasoning behind this comment...

... well, there is one reason that I can think of, but I'll discuss
that more below.

With this commit, if I define a parameter like this:

  (use-modules (gdb))
  (register-parameter! (make-parameter
                        "print test"
                        #:command-class COMMAND_NONE
                        #:parameter-type PARAM_BOOLEAN))

Then, in GDB, I now see this behaviour:

  (gdb) help show print test
  Show the current value of 'print test'.
  This command is not documented.
  (gdb) help set print test
  Set the current value of 'print test'.
  This command is not documented.
  (gdb)

The two 'This command is not documented.' lines are new.  This output
is what we get from a similarly defined parameter using the Python
API (see the previous commit for an example).

I mentioned above that I can think of one reason for the (now deleted)
comment in gdbscm_make_parameter about leaving the doc field as NULL,
and that is this: consider the following GDB behaviour:

  (gdb) help show style filename foreground
  Show the foreground color for this property.
  (gdb)

Notice there is only a single line of output.  If I want to get the
same behaviour from a parameter defined in Guile, I might try skipping
the #:doc argument, but (after this commit), if I do that, GDB will
auto-generate some text for me, giving two lines of output (see
above).

So, next, maybe I try setting #:doc to the empty string, but if I do
that, then I get this:

  (use-modules (gdb))
  (register-parameter! (make-parameter
                        "print test"
			#:doc ""
                        #:command-class COMMAND_NONE
                        #:parameter-type PARAM_BOOLEAN))

  (gdb) help show print test
  Show the current value of 'print test'.

  (gdb)

Notice the blank line, that's not what I wanted.  In fact, the only
way to get rid of the second line is to leave the 'doc' variable as
NULL in gdbscm_make_parameter, which, due to the new auto-generation,
is no longer possible.

This issue also existed in the Python API, and was addressed in
commit:

  commit 4b68d4ac98aec7cb73a4b276ac7dd38d112786b4
  Date:   Fri Apr 11 23:45:51 2025 +0100

      gdb/python: allow empty gdb.Parameter.__doc__ string

After this commit, an empty __doc__ string for a gdb.Parameter is
translated into a NULL pointer passed to the add_setshow_* command,
which means the second line of output is completely skipped.

And this commit includes the same solution for the Guile API.  Now,
with this commit, and the Guile parameter using an empty '#:doc'
string, GDB has the following behaviour:

  (gdb) help show print test
  Show the current value of 'print test'.
  (gdb)

This matches the output for a similarly defined parameter in Python.

diff --git a/gdb/NEWS b/gdb/NEWS
index a50f0979759b0d6edc35dfeb053604562b9f7053..691a13ab1a1d1ec6f3e320594428b6cd14e55ded 100644 (file)
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -151,6 +151,11 @@ info threads [-gid] [-stopped] [-running] [ID]...
   ** New constant PARAM_COLOR represents color type of a value
      of a <gdb:parameter> object.  Parameter's value is <gdb::color> instance.
 
+  ** Eliding the #:doc string from make-parameter now means that GDB
+     will use a default documentation string.  Setting #:doc to the
+     empty string for make-parameter means GDB will only display the
+     #:set_doc or #:show_doc strings in the set/show help output.
+
 * New remote packets
 
 binary-upload in qSupported reply

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index c6d889fb692da8ced25926f93372f55ced14687b..7b3f0a9757b7d19c2e580d53dec4702030cd31b4 100644 (file)
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -2098,8 +2098,10 @@ is the @code{<gdb:parameter>} object representing the parameter, and
 This function must return a string, and will be displayed to the user.
 @value{GDBN} will add a trailing newline.
 
-The argument @var{doc} is the help text for the new parameter.
-If there is no documentation string, a default value is used.
+The argument @var{doc} is the help text for the new parameter.  If
+there is no documentation string, a default value is used.  If the
+documentation string is empty, then @value{GDBN} will print just the
+@var{set-doc} and @var{show-doc} strings (see below).
 
 The argument @var{set-doc} is the help text for this parameter's
 @code{set} command.

diff --git a/gdb/guile/scm-param.c b/gdb/guile/scm-param.c
index bc6c605b59c97145294e4fa46572388aa6239395..5137847484453757cf2368d6d2750c93f1706fba 100644 (file)
--- a/gdb/guile/scm-param.c
+++ b/gdb/guile/scm-param.c
@@ -315,6 +315,7 @@ enum doc_string_type
 {
   doc_string_set,
   doc_string_show,
+  doc_string_description
 };
 
 /* A helper function which returns the default documentation string for
@@ -325,12 +326,19 @@ enum doc_string_type
 static char *
 get_doc_string (doc_string_type doc_type, const char *cmd_name)
 {
-  if (doc_type == doc_string_show)
-    return xstrprintf (_("Show the current value of '%s'."),
-                      cmd_name).release ();
+  if (doc_type == doc_string_description)
+    return xstrdup (_("This command is not documented."));
   else
-    return xstrprintf (_("Set the current value of '%s'."),
-                      cmd_name).release ();
+    {
+      gdb_assert (cmd_name != nullptr);
+
+      if (doc_type == doc_string_show)
+       return xstrprintf (_("Show the current value of '%s'."),
+                          cmd_name).release ();
+      else
+       return xstrprintf (_("Set the current value of '%s'."),
+                          cmd_name).release ();
+    }
 }
 
 /* Subroutine of pascm_set_func, pascm_show_func to simplify them.
@@ -1006,7 +1014,10 @@ gdbscm_make_parameter (SCM name_scm, SCM rest)
                              &show_doc_arg_pos, &show_doc,
                              &initial_value_arg_pos, &initial_value_scm);
 
-  /* If doc is NULL, leave it NULL.  See add_setshow_cmd_full.  */
+  if (doc == nullptr)
+    doc = get_doc_string (doc_string_description, nullptr);
+  else if (*doc == '\0')
+    doc = nullptr;
   if (set_doc == NULL)
     set_doc = get_doc_string (doc_string_set, name);
   if (show_doc == NULL)

diff --git a/gdb/testsuite/gdb.guile/scm-parameter.exp b/gdb/testsuite/gdb.guile/scm-parameter.exp
index a1bb374d4ad2b443b2f845128ba3253473976e09..06eebddf2423a466d06c532bd57309a77e8d4167 100644 (file)
--- a/gdb/testsuite/gdb.guile/scm-parameter.exp
+++ b/gdb/testsuite/gdb.guile/scm-parameter.exp
@@ -67,9 +67,19 @@ with_test_prefix "test-param" {
     gdb_test_no_output "set print test-param off"
     gdb_test "show print test-param" "The state of the Test Parameter is off." "show parameter off"
     gdb_test "guile (print (parameter-value test-param))" "= #f" "parameter value, false"
-    gdb_test "help show print test-param" "Show the state of the boolean test-param.*" "show help"
-    gdb_test "help set print test-param" "Set the state of the boolean test-param.*" "set help"
-    gdb_test "help set print" "set print test-param -- Set the state of the boolean test-param.*" "general help"
+    gdb_test "help show print test-param" \
+       [multi_line \
+            "^Show the state of the boolean test-param\\." \
+            "When enabled, test param does something useful\\. When disabled, does nothing\\."] \
+       "show help"
+    gdb_test "help set print test-param" \
+       [multi_line \
+            "^Set the state of the boolean test-param\\." \
+            "When enabled, test param does something useful\\. When disabled, does nothing\\."] \
+        "set help"
+    gdb_test "help set print" \
+       "set print test-param -- Set the state of the boolean test-param.*" \
+       "general help"
 
     gdb_test "guile (print (parameter? test-param))" "= #t"
     gdb_test "guile (print (parameter? 42))" "= #f"
@@ -315,12 +325,16 @@ with_test_prefix "test-undocumented-param" {
     gdb_test_no_output "set print test-undoc-param off"
     gdb_test "show print test-undoc-param" "The state of the Test Parameter is off." "show parameter off"
     gdb_test "help show print test-undoc-param" \
-       "Show the current value of 'print test-undoc-param'\\." "show help"
+       [multi_line \
+            "^Show the current value of 'print test-undoc-param'\\." \
+            "This command is not documented\\."] \
+       "show help"
     gdb_test "help set print test-undoc-param" \
-       "Set the current value of 'print test-undoc-param'\\." "set help"
-    gdb_test "help set print" \
-       "set print test-undoc-param -- Set the current value of 'print test-undoc-param'\\..*" \
-       "general help"
+       [multi_line \
+            "Set the current value of 'print test-undoc-param'\\." \
+            "This command is not documented\\."] \
+        "set help"
+    gdb_test "help set print" "set print test-undoc-param -- Set the current value of 'print test-undoc-param'\\..*" "general help"
 }
 
 # Test a parameter with a restricted range, where we need to notify the user
@@ -390,9 +404,15 @@ with_test_prefix "previously-ambiguous" {
        "The current value of 'print s' is on\\." "show parameter on"
     gdb_test "guile (print (parameter-value prev-ambig))" "= #t" "parameter value, true"
     gdb_test "help show print s" \
-       "Show the current value of 'print s'\\." "show help"
+       [multi_line \
+            "^Show the current value of 'print s'\\." \
+            "This command is not documented\\."] \
+       "show help"
     gdb_test "help set print s" \
-       "Set the current value of 'print s'\\." "set help"
+       [multi_line \
+            "Set the current value of 'print s'\\." \
+            "This command is not documented\\."] \
+       "set help"
     gdb_test "help set print" \
        "set print s -- Set the current value of 'print s'\\..*" \
        "general help"
@@ -443,6 +463,21 @@ gdb_test_multiline "create ambiguous 'foo baz' parameter" \
         "Out of range: could not find command prefix 'foo' in position 1: \"foo baz\"" \
         "Error while executing Scheme code."]
 
+with_test_prefix "empty doc string" {
+    gdb_test_multiline "empty doc string parameter" \
+       "guile" "" \
+       "(register-parameter! (make-parameter \"empty-doc-string\"" "" \
+       "   #:command-class COMMAND_NONE" "" \
+       "   #:parameter-type PARAM_ZINTEGER" "" \
+       "   #:doc \"\"" "" \
+       "   #:set-doc \"Set doc string.\"" "" \
+       "   #:show-doc \"Show doc string.\"))" "" \
+       "end"
+
+    gdb_test "help set empty-doc-string" "^Set doc string\\."
+    gdb_test "help show empty-doc-string" "^Show doc string\\."
+}
+
 rename scm_param_test_maybe_no_output ""
 
 # Test a color parameter.