gh-103143: Polish pdb help messages and doc strings #103144
Conversation
7217e6e to
c47a73c
Compare
Misc/NEWS.d/next/Library/2023-03-31-01-13-00.gh-issue-103143.6eMluy.rst
Outdated
Show resolved
Hide resolved
| @@ -945,7 +951,8 @@ def do_ignore(self, arg): | |||
| complete_ignore = _complete_bpnumber | |||
|
|
|||
| def do_clear(self, arg): | |||
| """cl(ear) filename:lineno\ncl(ear) [bpnumber [bpnumber...]] | |||
| """cl(ear) [filename:lineno | bpnumber ...] | |||
There was a problem hiding this comment.
This seems like a more accurate description, right?
| """cl(ear) [filename:lineno | bpnumber ...] | |
| """cl(ear) [filename:lineno] [bpnumber ...] |
There was a problem hiding this comment.
clear command takes either a filename:lineno or a list of bpnumber. [filename:lineno] [bpnumber ...] suggests that they could both exist, which won't work.
There was a problem hiding this comment.
Ah, I missed the early return on 990!
There was a problem hiding this comment.
Actually, now that I took at look at the code, this is not what I would write. I'd use three mutual exclusive if cases instead of early returns.
Lib/pdb.py
Outdated
| (com) ... | ||
| (com) end | ||
| (Pdb) |
There was a problem hiding this comment.
Just curious, why the indent?
There was a problem hiding this comment.
Just to align better in docstring. This is what the users see when they use this command.
There was a problem hiding this comment.
Hm, I sort of prefer it as is. It doesn't affect how pdb's help is formatted, but it does break help formatting for this function itself:
help(pdb.Pdb.do_commands) before:
Help on function do_commands in module pdb:
do_commands(self, arg)
commands [bpnumber]
(com) ...
(com) end
(Pdb)
Specify a list of commands for breakpoint number bpnumber.
After:
Help on function do_commands in module pdb:
do_commands(self, arg)
(Pdb) commands [bpnumber]
(com) ...
(com) end
(Pdb)
Specify a list of commands for breakpoint number bpnumber.
There was a problem hiding this comment.
Ah, inspect.cleandocs cleans up the common indent. Ok then, I guess we should not introduce the indent.
Co-authored-by: Brandt Bucher <[email protected]>
|
Thanks for the PR! |
|
Thank you for your time to review! |
|
No problem. Also, I'm surprised we don't have any tests for the help formatting. Maybe it's worth adding a couple of doctests to |
|
What do you have in your mind to check against? It's not like there's a "correct" format for docs. We can make sure that all commands have help message. The format is rather arbitrary right? |
|
Status check is done, and it's a success ✅. |
…03144) * Made all the command part of the docstring match the official documentation * Always have a space between the command and the description in docstring * Added a helper function to format the help message Before: ``` (Pdb) h a a(rgs) Print the argument list of the current function. (Pdb) h commands commands [bpnumber] (com) ... (com) end (Pdb) ... (Pdb) h interact interact Start an interactive interpreter whose global namespace contains all the (global and local) names found in the current scope. ``` After ``` (Pdb) h a Usage: a(rgs) Print the argument list of the current function. (Pdb) h commands Usage: (Pdb) commands [bpnumber] (com) ... (com) end (Pdb) ... (Pdb) h interact Usage: interact Start an interactive interpreter whose global namespace contains all the (global and local) names found in the current scope. ``` Automerge-Triggered-By: GH:brandtbucher
Before:
After
Automerge-Triggered-By: GH:brandtbucher