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.  :)

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?

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?

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?

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).

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."

May be just provide Python statements that correspond different numbers of parameters? 0 -- ``raise``, 1 -- ``raise TOS``, 2 -- ``raise TOS1 from TOS``.

I've made a PR, could serhiy or georg help for review?
Thanks!

The original PR appears to have been abandoned, so this issue available for someone to submit a new PR.

I'm working on it.

New changeset e1179a5096fb12297ececd7a1c79969aa5747e28 by Ezio Melotti (Michele Angrisano) in branch 'master':
bpo-19184: Update the documentation of dis module. (GH-13652)
https://github.com/python/cpython/commit/e1179a5096fb12297ececd7a1c79969aa5747e28

New changeset 9390e98c3ed9eb9fa414030a2feec1926193af94 by Ezio Melotti (Miss Islington (bot)) in branch '3.7':
bpo-19184: Update the documentation of dis module. (GH-13652) (GH-13755)
https://github.com/python/cpython/commit/9390e98c3ed9eb9fa414030a2feec1926193af94

Fixed, thanks for the report and the PRs!