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

[Michele Angrisano]

Change by Michele Angrisano :


--
keywords: +patch
pull_requests: +13268
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Michele Angrisano]

Michele Angrisano  added the comment:

If Aaron can't working on it, I can do it. Just tell me.

Thanks.

--
nosy: +Michele Angrisano

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[SilentGhost]

SilentGhost  added the comment:

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 ?

--
nosy: +SilentGhost
stage:  -> needs patch
type:  -> behavior
versions: +Python 3.7 -Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Aaron Hall]

New submission from Aaron Hall :

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com