New submission from Aaron Hall <aaronchall@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@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 <report@bugs.python.org> <https://bugs.python.org/issue36927> _______________________________________