The show doc is not shown properly. In the next example the show_doc is totally different from the output that's actually shown. Not only does it drop everything after the '.', it also manages to translate 'This' to 'Is'. (gdb) python >class Param(gdb.Parameter): > show_doc = "This is the show doc. This part is not shown!" > >Param("some-param", gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN) >end (gdb) show some-param Is the show doc is off.
There are actually a few bugs here: This is wrong as noted in the bug: (gdb) show some-param Is the show doc is off. Not sure where show doc is being pulled from. Anyway, the variable "show_doc" should be printed from the help. It is, but for some reason GDB notes this command is not documented right after it printed the documentation. (gdb) help show some-param This is the show doc. This part is not shown! This command is not documented.
Well I was wrong, these are not bugs. Just a weird implementation inside GDB: Take your example: class Param(gdb.Parameter): """some-param is a switch that does nothing at all. You can set it and show it as much as you like.""" show_doc = "Show the some-param switch" set_doc = "Set the some-param switch to on or off. " Param("some-param", gdb.COMMAND_NONE, gdb.PARAM_BOOLEAN) (gdb) show some-param The some-param switch is off. (gdb) help show some-param Show the some-param switch some-param is a switch that does nothing at all. You can set it and show it as much as you like. (gdb) help set some-param Set the some-param switch to on or off. some-param is a switch that does nothing at all. You can set it and show it as much as you like. When you "show" a parameter, the show_doc documentation is used and then the value appended at the end (in this case, "off"). GDB trims off the first five letters of the show documentations (the "Show") so it can reuse it for both the help text and the value assignment text. Ditto for the Set. So the example above "works". The "command is not documented" is printed if either show_doc, set_doc or doc is not set in the parameter. Maybe we need a better explanation in the manual?
(In reply to comment #2) On Tuesday 16 November 2010 14:32:01, pmuldoon at redhat dot com wrote: > When you "show" a parameter, the show_doc documentation is used and then the > value appended at the end (in this case, "off"). GDB trims off the first five > letters of the show documentations (the "Show") so it can reuse it for both the > help text and the value assignment text. Ditto for the Set. FYI, that's deprecated behavior that is going away at some point. All commands should implement the necessary show-current-state callback so that that fallback does not need to apply. The reason that is broken is that it only works for English... At some point, I'd like to make a pass through all commands in GDB, implement all the missing callbacks, get rid of that fallback code, and put an assertion on place making sure the command implements a show callback. > So the example above "works". > > > The "command is not documented" is printed if either show_doc, set_doc or doc > is not set in the parameter. > > Maybe we need a better explanation in the manual? I've no clue on the Python API, is there a way to implement the "show" callback of a parameter? If not, there should be. If yes, it should be a requirement to implement it, per the rationale I mention above. -- Pedro Alves
Yeah, we can. First we would have to identify the parameter as being written in Python. Then we would require the user to implement show/set documentation functions in Python. Then, when the value printing/help parameter code sections are executed in GDB we can check if it is a Python scripted parameter, and if so then call into the Python object where it would return the appropriate string for the above functions. This would be an API regression on our part though. We might be able to do this generically which would avoid requiring parameter API changes, but not sure how.
(In reply to comment #4) > Yeah, we can. > First we would have to identify the parameter as being written > in Python. I don't think you need this. Looking at py-param.c:add_setshow_generic, you're currently always passing NULL as both set_func and show_func callbacks. I'd like to make this illegal at some point. You'd instead pass a pointer to py-param.c specific callbacks, and then these new callbacks' implementation would know to call the corresponding callback on the Python (language) side. As a first step, this can be make optional, with the current behavior as fallback, of course. > Then we would require the user to implement show/set documentation > functions in Python. At some point, yes. With i18n, it's necessary. As a first step, we should at least add the possibility to implement the callback. This callback is also the way some commands can show the "(currently foo)" part: As I understand it, it's not possible do have a param do that in python currently. E.g.,: (gdb) show breakpoint always-inserted Always inserted breakpoint mode is auto (currently off). > Then, when the value printing/help parameter code > sections are executed in GDB we can check if it is a Python scripted parameter, > and if so then call into the Python object where it would return the > appropriate string for the above functions. Well, no need for the generic code to know this is a python parameter --- the generic code just calls the installed callback through a function pointer as usual. But instead of getting the default callback implementation (cli/cli-setshow.c:deprecated_show_value_hack), it'd call a new python/py-param.c:py_show_param_value function. > > This would be an API regression on our part though. We might be able to do this > generically which would avoid requiring parameter API changes, but not sure > how.
This bug has been fixed with this check-in. CVSROOT: /cvs/src Module name: src Changes by: pmuldoon@sourceware.org 2011-03-10 12:29:08 Modified files: gdb : ChangeLog gdb/doc : ChangeLog gdb.texinfo gdb/python : py-param.c gdb/testsuite : ChangeLog gdb/testsuite/gdb.python: py-parameter.exp Log message: 2011-03-10 Phil Muldoon <pmuldoon@redhat.com> * python/py-param.c (add_setshow_generic): Add set/show callback parameters. Register Python object context. (get_show_value): New function. (get_set_value): New function. (call_doc_function): New function. (get_doc_string): Move behind get_show_value/get_set_value. 2011-03-10 Phil Muldoon <pmuldoon@redhat.com> * gdb.texinfo (Parameters In Python): Document get_set_string and get_show_string methods. 2011-03-10 Phil Muldoon <pmuldoon@redhat.com> * gdb.python/py-parameter.exp: Update tests to the new Python parameter API. Add "no documentation" test. Add deprecated API backward compatibility test. Patches: http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/ChangeLog.diff?cvsroot=src&r1=1.12782&r2=1.12783 http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/doc/ChangeLog.diff?cvsroot=src&r1=1.1161&r2=1.1162 http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/doc/gdb.texinfo.diff?cvsroot=src&r1=1.809&r2=1.810 http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/python/py-param.c.diff?cvsroot=src&r1=1.9&r2=1.10 http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/testsuite/ChangeLog.diff?cvsroot=src&r1=1.2627&r2=1.2628 http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/testsuite/gdb.python/py-parameter.exp.diff?cvsroot=src&r1=1.3&r2=1.4
*** Bug 12550 has been marked as a duplicate of this bug. ***