As part of adding support for Python 3.12 to https://github.com/MatthieuDartiailh/bytecode I have identified a number of documentation issues both in the dismodule documentation in the bytecode section of the What's new in 3.12. Opening a separate issue for each point would just clutter the issue tracker so I will try to summarize all my findings here.

Issue in dis documentation

• COMPARE_OP oparg now uses the 4 lower bits as a cache. As a consequence:
  • the statement The operation name can be found in cmp_op[opname] is not true anymore.
  • the meaning of the cache is not documented but it can be != 0 even for a freshly compiled bytecode and as a consequence the difference is visible in dis.dis output
• MIN_INSTRUMENTED_OPCODE is not documented but needed to determine what are the "normal" opcodes
• LOAD_SUPER_ATTR description could use a code block to describe its stack effect IMO
• POP_JUMP_IF_NOT_NONE and POP_JUMP_IF_NONE are still described as pseudo-instructions even though there are not anymore in 3.12
• CALL_INSTRINSIC_2 stack manipulation description looks wrong.
  The description reads Passes STACK[-2], STACK[-1] as the arguments and sets STACK[-1] to the result, but the implementation pops 2 values from the stack
• END_SEND is not documented
• how to account for the presence of CACHE instructions following jumping instructions is not described (FOR_ITER and SEND for the time being)

Issue in What's new

• BINARY_SLICE is not mentioned
• STORE_SLICE is not mentioned
• CLEANUP_THROW is not mentioned
• RETURN_CONST is not mentioned
• LOAD_FAST_CHECK is not mentioned
• END_SEND is not mentioned
• CALL_INSTRINSIC_1/2 are not mentioned
• FOR_ITER new behavior is not mentioned
• The fact that POP_JUMP_IF_* family of instructions are now real instructions is not mentioned
• YIELD_VALUE need for an argument is not mentioned
• The addition of dis.hasexc is not mentioned

Linked PRs

• gh-107457: update dis documentation with changes in 3.12 #108900
• [3.12] gh-107457: update dis documentation with changes in 3.12 (GH-108900) #110985