)]}'
{
  "commit": "4b68d4ac98aec7cb73a4b276ac7dd38d112786b4",
  "tree": "185455c781e2cdc0984627c2c0b98c43e9f93701",
  "parents": [
    "3e87f196c5c35e3e071ef0cdd14666d2c97d3f51"
  ],
  "author": {
    "name": "Andrew Burgess",
    "email": "aburgess@redhat.com",
    "time": "Fri Apr 11 23:45:51 2025 +0100"
  },
  "committer": {
    "name": "Andrew Burgess",
    "email": "aburgess@redhat.com",
    "time": "Tue May 13 14:33:20 2025 +0100"
  },
  "message": "gdb/python: allow empty gdb.Parameter.__doc__ string\n\nI was recently attempting to create some parameters via the Python\nAPI.  I wanted these parameters to appear similar to how GDB handles\nthe existing \u0027style\u0027 parameters.\n\nSpecifically, I was interested in this behaviour:\n\n  (gdb) help show style filename foreground\n  Show the foreground color for this property.\n  (gdb) help set style filename foreground\n  Set the foreground color for this property.\n  (gdb)\n\nNotice how each \u0027help\u0027 command only gets a single line of output.\n\nI tried to reproduce this behaviour via the Python API and was unable.\n\nThe problem is that, in order to get just a single line of output like\nthis, the style parameters are registered with a call to\nadd_setshow_color_cmd with the \u0027help_doc\u0027 being passed as nullptr.\n\nOn the Python side, when parameters are created, the \u0027help_doc\u0027 is\nobtained with a call to get_doc_string (python/py-param.c).  This\nfunction either returns the __doc__ string, or a default string: \"This\ncommand is not documented.\".\n\nTo avoid returning the default we could try setting __doc__ to an\nempty string, but setting this field to any string means that GDB\nprints a line for that string, like this:\n\n  class test_param(gdb.Parameter):\n     __doc__ \u003d \"\"\n     def __init__(self, name):\n        super ().__init__(name, gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN)\n        self.value \u003d True\n\n  test_param(\u0027print test\u0027)\n\nThen in GDB:\n\n  (gdb) help set print test\n  Set the current value of \u0027print test\u0027.\n\n  (gdb)\n\nThe blank line is the problem I\u0027d like to solve.\n\nThis commit makes a couple of changes to how parameter doc strings are\nhandled.\n\nIf the doc string is set to an empty string, then GDB now converts\nthis to nullptr, which removes the blank line problem, the new\nbehaviour in GDB (for the above `test_param`) is:\n\n  (gdb) help set print test\n  Set the current value of \u0027print test\u0027.\n  (gdb)\n\nNext, I noticed that if the set/show docs are set to empty strings,\nthen the results are less than ideal:\n\n  class test_param(gdb.Parameter):\n     set_doc \u003d \"\"\n     def __init__(self, name):\n        super ().__init__(name, gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN)\n        self.value \u003d True\n\n  test_param(\u0027print test\u0027)\n\nAnd in GDB:\n\n  (gdb) help set print test\n\n  This command is not documented.\n  (gdb)\n\nSo, if the set/show docs are the empty string, GDB now forces these to\nbe the default string instead, the new behaviour in GDB is:\n\n  (gdb) help set print test\n  Set the current value of \u0027print test\u0027.\n  This command is not documented.\n  (gdb)\n\nI\u0027ve added some additional asserts; the set/show docs should always be\nnon-empty strings, which I believe is the case after this commit.  And\nthe \u0027doc\u0027 string returned from get_doc_string should never nullptr,\nbut could be empty.\n\nThere are new tests to cover all these changes.\n",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "d3699de1653275ad8b8f2c97321ebe494d221b46",
      "old_mode": 33188,
      "old_path": "gdb/NEWS",
      "new_id": "a50f0979759b0d6edc35dfeb053604562b9f7053",
      "new_mode": 33188,
      "new_path": "gdb/NEWS"
    },
    {
      "type": "modify",
      "old_id": "7bb650347f7735217f90932b81be9b1e3a5c40d8",
      "old_mode": 33188,
      "old_path": "gdb/doc/python.texi",
      "new_id": "1a2d7724aa743d2026c469a3da9488a339727c53",
      "new_mode": 33188,
      "new_path": "gdb/doc/python.texi"
    },
    {
      "type": "modify",
      "old_id": "763680e3ddaebccbbff9fde86e5a08d2432d1dc6",
      "old_mode": 33188,
      "old_path": "gdb/python/py-param.c",
      "new_id": "06237b6f1b3ea7b0a9efc42b062578707a5a4ec0",
      "new_mode": 33188,
      "new_path": "gdb/python/py-param.c"
    },
    {
      "type": "modify",
      "old_id": "39a24ca1663ea4f0da1a4864f76974d29758937f",
      "old_mode": 33188,
      "old_path": "gdb/testsuite/gdb.python/py-parameter.exp",
      "new_id": "2ca56dc83fc6cd615dcc283b43c4c10c9da1500a",
      "new_mode": 33188,
      "new_path": "gdb/testsuite/gdb.python/py-parameter.exp"
    }
  ]
}