[Bug python/12175] New: show_doc for gdb.Parameter has strange behaviour

[Bug python/12175] New: show_doc for gdb.Parameter has strange behaviour

[markflorisson88 at gmail dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

           Summary: show_doc for gdb.Parameter has strange behaviour
           Product: gdb
           Version: 7.1
            Status: NEW
          Severity: normal
          Priority: P2
         Component: python
        AssignedTo: unassigned@sourceware.org
        ReportedBy: markflorisson88@gmail.com


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.

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[markflorisson88 at gmail dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

Mark Florisson <markflorisson88 at gmail dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
            Version|7.1                         |7.2

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pmuldoon at redhat dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

Phil Muldoon <pmuldoon at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
                 CC|                            |pmuldoon at redhat dot com

--- Comment #1 from Phil Muldoon <pmuldoon at redhat dot com> 2010-11-16 12:14:19 UTC ---
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.

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pmuldoon at redhat dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

Phil Muldoon <pmuldoon at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|unassigned at sourceware    |pmuldoon at redhat dot com
                   |dot org                     |

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pmuldoon at redhat dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

--- Comment #2 from Phil Muldoon <pmuldoon at redhat dot com> 2010-11-16 14:31:51 UTC ---
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?

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pedro at codesourcery dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

Pedro Alves <pedro at codesourcery dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |pedro at codesourcery dot
                   |                            |com

--- Comment #3 from Pedro Alves <pedro at codesourcery dot com> 2010-11-16 14:49:03 UTC ---
(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

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pmuldoon at redhat dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

--- Comment #4 from Phil Muldoon <pmuldoon at redhat dot com> 2010-11-16 15:14:09 UTC ---
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.

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pedro at codesourcery dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

--- Comment #5 from Pedro Alves <pedro at codesourcery dot com> 2010-11-16 15:30:13 UTC ---
(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.

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pmuldoon at redhat dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

Phil Muldoon <pmuldoon at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |RESOLVED
         Resolution|                            |FIXED
   Target Milestone|---                         |7.3

--- Comment #6 from Phil Muldoon <pmuldoon at redhat dot com> 2011-03-14 17:56:57 UTC ---
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

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

[Bug python/12175] show_doc for gdb.Parameter has strange behaviour

[pmuldoon at redhat dot com]

http://sourceware.org/bugzilla/show_bug.cgi?id=12175

Phil Muldoon <pmuldoon at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |joachim.protze at zih dot
                   |                            |tu-dresden.de

--- Comment #7 from Phil Muldoon <pmuldoon at redhat dot com> 2011-03-16 10:29:45 UTC ---
*** Bug 12550 has been marked as a duplicate of this bug. ***

-- 
Configure bugmail: http://sourceware.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.