New submission from Aaron Hall <[email protected]>:
I've written three (or more) answers on Stack Overflow about how to use the
functions in the traceback module, and I code Python all day long.
Embarrassing confession: I just recommended the wrong traceback function in
email to fix the incorrect usage of another of these functions after pulling up
the docs because. I corrected myself before anyone else could correct me, but I
find these docstrings incredibly frustrating and problematic.
May I please give them a little more verbiage about their return values?
e.g.:
def format_tb(tb, limit=None):
"""A shorthand for 'format_list(extract_tb(tb, limit))'."""
return extract_tb(tb, limit=limit).format()
should be:
def format_tb(tb, limit=None):
"""A shorthand for 'format_list(extract_tb(tb, limit))',
which returns a list of strings ready for printing'.
"""
return extract_tb(tb, limit=limit).format()
In fact, perhaps the "shorthand" part is an implementation detail that may not
even be correct (it doesn't immediately seem to be) and should be removed.
----------
assignee: docs@python
components: Documentation
messages: 342588
nosy: Aaron Hall, docs@python
priority: normal
severity: normal
status: open
title: traceback docstrings should explicitly state return values instead of
referring to other functions
versions: Python 3.8, Python 3.9
_______________________________________
Python tracker <[email protected]>
<https://bugs.python.org/issue36927>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
