classification
Title: Bdb: add docstrings
Type: enhancement Stage: commit review
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: cheryl.sabella, docs@python, terry.reedy
Priority: normal Keywords:

Created on 2017-04-29 19:54 by cheryl.sabella, last changed 2017-05-17 00:43 by terry.reedy.

Pull Requests
URL Status Linked Edit
PR 1350 merged cheryl.sabella, 2017-04-29 19:54
Messages (8)
msg292598 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-04-29 19:54
Add docstrings to Bdb.  See issue 19417.
msg293743 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-16 01:24
In the entry at https://docs.python.org/3/library/bdb.html#bdb.Bdb.canonic, 
", stripped of surrounding angle brackets"
is wrong, and should be replaced by
".  'Filenames' with angle brackets, such as "<stdin>", generated in interactive mode, are returned unchanged"

>>> 1/0
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero

(IDLE generates "<PyShell#n>", when n is statement number, starting with 0.)

This and any other doc errors we find should be corrected in this issue, but perhaps in a separate PR that can be backported separately.
msg293744 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-16 01:26
As I just posted to core-mentorship, my attempt to push to the PR failed.  Did you leave the 'allow pushes' box checked when you created the PR?
msg293752 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-16 06:35
The bdb class or __init__ docstring needs to document the data members with a short explanation.  Some of the args need better explanation.  Some of this I may fill in *after* reviewing the proposed tests, when I understand the code better.  Reviewing pdb and IDLE's Idb and Debugger (my real interest here) will help.

is_skipped_module is public, by its name, but is not in the doc.

break_here: " If the breakpoint is a temporary one, this method deletes it."  maybe (if flag from effective is True)

The first comment and the code that follows do not seem to match.  IDLE does not set breakpoints for functions, so I cannot test the behavior here with its debugger.

set_break doc says filename should be canonic, but function then calls canonic.  So canonic not needed.  If it is, result is self.fncache[canonic_filename] = self.fncache[canonic_filename].  But I will leave suggestion as is for now.

get_stack: return 'size of the higher part': If higher part does not stop as self.botframe (which might be None?), the size is of the lower part.  I need to review frame and tb objects pin down this docstring.

I just pushed my changes.  Please review for typos and anything you think is a new error.  Otherwise, I think this is about good enough to merge.
msg293763 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-05-16 13:31
Thank you.  I had some questions that I put on the commit.

You're right about it saying it must be in canonic form and then it calls canonic.  I figured someone added the call later to prevent an error, but didn't change the warning, but I didn't know if I should change it.

I added a comment about get_stack on github.  I know I'm missing something here, but I had trouble documenting that because it didn't look like it was doing what the doc said.

I'm not at my regular computer this week, so I can't add any changes until Saturday.  I'll do the is_skipped_module doc then.

Thank you for the edits on the other docstrings.  They make a lot more sense now.  Although I still don't like the user_* ones.  I hadn't changed them from the original before, but it feels like they should say something else, like what's expected of them.  The test example within bdb.py helped me understand what can be done with them.
msg293782 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-16 20:48
I plan to merge when I can.  Possible future improvements for bdb.py.

1. Bdb attributes.
2. Say what user_xyz functions might do.  Anything better than 'Intervene in debugging process.'?
3. Clarify what get_stack does.

Improvement for bdb.rst (optional for this issue).
1. Add is_skipped_module
2. Fix overt errors we are sure of, noted above
* canonic: <> not stripped
* break_here: temps *may* be deleted
* get_stack: length may or may not be what says.
msg293813 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-16 22:28
New changeset 0774e79b93cc494b3a957d538c7c112e289973c0 by terryjreedy (csabella) in branch 'master':
bpo-30211: bdb: add docstrings (#1350)
https://github.com/python/cpython/commit/0774e79b93cc494b3a957d538c7c112e289973c0
msg293831 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-05-17 00:43
I still need to push a News Entry.
History
Date User Action Args
2019-04-12 17:46:24xdegayeunlinkissue19417 dependencies
2017-05-17 00:43:10terry.reedysetmessages: + msg293831
2017-05-16 22:28:04terry.reedysetmessages: + msg293813
2017-05-16 20:48:10terry.reedysetmessages: + msg293782
2017-05-16 13:31:09cheryl.sabellasetmessages: + msg293763
2017-05-16 06:35:27terry.reedysetmessages: + msg293752
stage: commit review
2017-05-16 01:26:27terry.reedysetmessages: + msg293744
2017-05-16 01:24:56terry.reedysetassignee: docs@python -> terry.reedy
messages: + msg293743
2017-04-30 11:39:09cheryl.sabellasetcomponents: + Documentation, - IDLE
2017-04-30 11:38:59cheryl.sabellasetcomponents: + IDLE, - Documentation
2017-04-29 20:49:53terry.reedylinkissue19417 dependencies
2017-04-29 19:54:20cheryl.sabellacreate