gdb/guile: improve auto-generated strings for parameters

Consider this user defined parameter created in Python:

  class test_param(gdb.Parameter):
     def __init__(self, name):
        super ().__init__(name, gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN)
        self.value = True

  test_param('print test')

If this is loaded into GDB, then we observe the following behaviour:

  (gdb) show print test
  The current value of 'print test' is "on".
  (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)

If we now define the same parameter using Guile:

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

And load this into a fresh GDB session, we see the following:

  (gdb) show print test
  Command is not documented is off.
  (gdb) help show print test
  This command is not documented.
  (gdb) help set print test
  This command is not documented.
  (gdb)

The output of 'show print test' doesn't make much sense, and is
certainly worse than the Python equivalent.  For both the 'help'
commands it appears as if the first line is missing, but what is
actually happening is that the first line has become 'This command is
not documented.', and the second line is then missing.

The problems can all be traced back to 'get_doc_string' in
guile/scm-param.c.  This is the guile version of this function.  There
is a similar function in python/py-param.c, however, the Python
version returns one of three different strings depending on the use
case.  In contrast, the Guile version just returns 'This command is
not documented.' in all cases.

The three cases that the Python code handles are, the 'set' string,
the 'show' string, and the general 'description' string.

Right now the Guile get_doc_string only returns the general
'description' string, which is funny, because, in
gdbscm_make_parameter, where get_doc_string is used, the one case that
we currently don't need is the general 'description' string.  Instead,
right now, the general 'description' string is used for both the 'set'
and 'show' cases.

In this commit I plan to bring the Guile API a little more inline with
the Python API.  I will update get_doc_string (in scm-param.c) to
return either a 'set' or 'show' string, and gdbscm_make_parameter will
make use of these strings.

The changes to the Guile get_doc_string are modelled on the Python
version of this function.  It is also worth checking out the next
commit, which is related, and helps motivate how the changes have been
implemented in this commit.

After this commit, the same Guile parameter description shown above,
now gives this behaviour:

  (gdb) show print test
  The current value of 'print test' is off.
  (gdb) help show print test
  Show the current value of 'print test'.
  (gdb) help set print test
  Set the current value of 'print test'.
  (gdb)

The 'show print test' output now matches the Python behaviour, and is
much more descriptive.  The set and show 'help' output are now missing
the second line when compared to the Python output, but the first line
is now correct, and I think this is better than the previous Guile
output.

In the next commit I'll address the problem of the missing second
line.

Existing tests have been updated to expect the new output.

0 files changed, 0 insertions, 0 deletions