Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Sign upbpo-39278: add docstrings to functions in pdb module #17924
Conversation
Thanks for the PR @carlbordum. IMO, it's always helpful to keep the docstrings up to date with the documentation. I've verified that the changes match the documentation at https://docs.python.org/3/library/pdb.html. The only thing that's missing is a few formatting conversions, particularly the words that should be italics. In docstrings, we typically surround parameter names with asterisks (only for the first occurrence in each docstring though). I'll include the missing ones in suggestions below. The only other thing you could consider including would be a docstring for the |
return Pdb().runeval(expression, globals, locals) | ||
|
||
def runctx(statement, globals, locals): | ||
# B/W compatibility | ||
run(statement, globals, locals) | ||
|
||
def runcall(*args, **kwds): | ||
"""Call the function (a function or method object, not a string) |
This comment has been minimized.
This comment has been minimized.
aeros
Jan 9, 2020
Member
"""Call the function (a function or method object, not a string) | |
"""Call the *function* (a function or method object, not a string) |
This comment has been minimized.
This comment has been minimized.
carlbordum
Jan 10, 2020
Author
Contributor
Thanks for the review! I went ahead and changed what you asked for except for this one case. I am not sure "function" should be italic as the name is not in the signature. What do you think?
@@ -1614,6 +1646,12 @@ def set_trace(*, header=None): | |||
# Post-Mortem interface | |||
|
|||
def post_mortem(t=None): |
This comment has been minimized.
This comment has been minimized.
aeros
Jan 9, 2020
•
Member
Here's another discrepancy between the docs and the function signature. This one is a bit less significant, but I find it odd that the signature uses t as the parameter name while the documentation uses traceback.
I'd be in favor of adjusting the documentation here, as it could lead to issues if a user tries to pass a keyword argument to traceback. For example: pdb.post_mortem(traceback=tb)
would lead to a rather confusing TypeError
.
Once again, not directly related to the PR but worth noting.
All these functions were already documented, but not in docstrings which means you could not call help() on the functions before this patch.
carlbordum commentedJan 9, 2020
•
edited by bedevere-bot
All these functions were already documented, but not in docstrings which
means you could not call help() on the functions before this patch.
https://bugs.python.org/issue39278