classification
Title: traceback docstrings should explicitly state return values instead of referring to other functions
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Aaron Hall, SilentGhost, docs@python, mangrisano
Priority: normal Keywords: patch

Created on 2019-05-15 17:04 by Aaron Hall, last changed 2019-05-16 13:36 by mangrisano.

Pull Requests
URL Status Linked Edit
PR 13359 open mangrisano, 2019-05-16 13:36
Messages (3)
msg342588 - (view) Author: Aaron Hall (Aaron Hall) * Date: 2019-05-15 17:04
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.
msg342589 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2019-05-15 17:21
The doc strings were never updated in #17911. Would you like to submit a PR for these changes? (guidelines are available at https://devguide.python.org/pullrequest/) Perhaps, you could include similar changes in Doc/library/traceback.rst ?
msg342633 - (view) Author: Michele Angrisano (mangrisano) * Date: 2019-05-16 10:06
If Aaron can't working on it, I can do it. Just tell me.

Thanks.
History
Date User Action Args
2019-05-16 13:36:45mangrisanosetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request13268
2019-05-16 10:06:57mangrisanosetnosy: + mangrisano
messages: + msg342633
2019-05-15 17:21:10SilentGhostsetversions: + Python 3.7, - Python 3.9
nosy: + SilentGhost

messages: + msg342589

type: behavior
stage: needs patch
2019-05-15 17:04:45Aaron Hallcreate