Add docstrings to Bdb. See bpo-19417.

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.

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?

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.

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.

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.

New changeset 0774e79 by terryjreedy (csabella) in branch 'master':
bpo-30211: bdb: add docstrings (bpo-1350)
0774e79

I still need to push a News Entry.

Taking a look at bdb.py, the methods have docstrings, and the __init__ args are documented in the docstrings of the classes, so looks like this is resolved.

Thank you. Whether I did or did not add a news entry 5 years ago is irrelevant now.