[New-bugs-announce] [issue36927] traceback docstrings should explicitly state return values instead of referring to other functions

[Aaron Hall]

New submission from Aaron Hall <aaronchall at yahoo.com>:

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 at python
components: Documentation
messages: 342588
nosy: Aaron Hall, docs at 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 <report at bugs.python.org>
<https://bugs.python.org/issue36927>
_______________________________________