classification
Title: dis module has incorrect docs for RAISE_VARARGS
Type: Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Tyler.B, docs@python, georg.brandl, louielu, nedbat, serhiy.storchaka
Priority: normal Keywords: easy

Created on 2013-10-06 16:46 by nedbat, last changed 2017-04-26 06:51 by louielu.

Pull Requests
URL Status Linked Edit
PR 1159 open louielu, 2017-04-16 04:29
Messages (8)
msg199096 - (view) Author: Ned Batchelder (nedbat) * Date: 2013-10-06 16:46
The order of values on the stack is backwards for RAISE_VARARGS.  The docs say:

"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS."

But in fact, the order is reverse of that.  In the one-parameter case, the exception is TOS, in the two-parameter case, the value is TOS, and in the three-parameter case, the traceback is TOS.  Not sure how to write that concisely, thought.  :)
msg199970 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-15 00:44
Looked at the code and found differences between 3.4 and 2.7. 2.7 has 3 exceptions that can be raised while 3.4 has 4 exceptions. 

I propose removing the "list of parameters" from the documenation to keep things simple and not repeat the code. 

# 2.7
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters consist of the traceback as TOS1, the value as TOS2, the exception as TOS3, and None as TOS4."

# 3.4  
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters consist of the cause as TOS1, the exception as TOS2, and None as TOS3."

How does this sound?
msg199989 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-15 10:24
I wanted to make an edit so here's my revised comment:

Looked at the code and found differences between 3.4 and 2.7. 2.7 has 4 exceptions that can be raised while 3.4 has 3 exceptions. 

I propose removing the "list of parameters" from the documenation to keep things simple and not repeat the code. 

# 2.7
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters consist of the traceback as TOS1, the value as TOS2, the exception as TOS3, and None as TOS4."

# 3.4  
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters consist of the cause as TOS1, the exception as TOS2, and None as TOS3."

How does this sound?
msg199992 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-15 10:37
One last edit:

Looked at the code and found differences between 3.4 and 2.7. 2.7 has 4 exceptions that can be raised while 3.4 has 3 exceptions. 

I propose including the full list of parameters but describing the exceptions in a way that's less specific about the TOS order to keep the documentation as simple as possible.   

# 2.7
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters can consist of the traceback as TOS1, the value as TOS2, the exception as TOS3, and None as TOS4."

# 3.4  
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters can consist of the cause as TOS1, the exception as TOS2, and None as TOS3."

How does this sound?
msg199994 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-15 11:32
Tyler, thanks for the suggestion.  However it doesn't really solve the issue: the parameter order is the opposite of the current doc text (and your suggested text).
msg200031 - (view) Author: Tyler B (Tyler.B) Date: 2013-10-16 00:50
Here's a revised suggestion that has the order changed. I have additional concerns but please provide comment on this revision. Thanks

# 2.7
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The parameters can consist of None as TOS1, the exception as TOS2, the value as TOS3, and the traceback as TOS4."

# 3.4  
"Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 2. The parameters can consist of None as TOS1, the exception as TOS2, and the cause as TOS3."
msg291758 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-04-16 16:57
May be just provide Python statements that correspond different numbers of parameters? 0 -- ``raise``, 1 -- ``raise TOS``, 2 -- ``raise TOS1 from TOS``.
msg292309 - (view) Author: Louie Lu (louielu) * Date: 2017-04-26 06:51
I've made a PR, could serhiy or georg help for review?
Thanks!
History
Date User Action Args
2017-04-26 06:51:31louielusetnosy: + louielu
messages: + msg292309
2017-04-16 16:57:52serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg291758
2017-04-16 04:29:43louielusetpull_requests: + pull_request1288
2017-04-15 07:06:10serhiy.storchakasetstage: needs patch
versions: + Python 3.5, Python 3.6, Python 3.7, - Python 3.4
2013-10-16 00:50:10Tyler.Bsetmessages: + msg200031
2013-10-15 11:32:38georg.brandlsetnosy: + georg.brandl
messages: + msg199994
2013-10-15 10:37:13Tyler.Bsetmessages: + msg199992
2013-10-15 10:24:53Tyler.Bsetmessages: + msg199989
2013-10-15 00:44:16Tyler.Bsetnosy: + Tyler.B
messages: + msg199970
2013-10-06 16:46:52nedbatcreate