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.

0 files changed, 0 insertions, 0 deletions