Bytecode interpreter section: provide a full specification of each opcode #1078
Labels
enhancement
guide-new content
Additions; New content or section needed
needs: decision
Needs consensus decision from core devs
Describe the enhancement or feature you'd like
The documentation for the
dis
module provide a summary of what each opcode does. However, the summary is not enough to fully understand what each opcode actually does. For instance, the documentation for SEND:(https://docs.python.org/3/library/dis.html#opcode-SEND)
yield from
(i.e. the context in which SEND is used).I propose a full spec be given in a format that looks like this:
For the SEND opcode, it would look like this:
This is similar to how the Java virtual machine documents its opcodes (https://docs.oracle.com/javase/specs/jvms/se7/html/jvms-6.html), with an additional section describing sources where the opcode are emitted.
Describe alternatives you've considered
dis
instead. Arguably, since a full specification need to dive deep into specific details, some CPython internals would leak into an otherwise user readable doc. Additionally, it increases the maintenance burden ondis
's documentation (which currently only need to list each opcode with a brief description).Additional context
For the majority of CPython 3.11 bytecodes, I have already written documentation for them using the above format (in Asciidoc): https://github.com/Christopher-Chianelli/optapy/blob/jpyinterpreter-docs/jpyinterpreter-docs/src/modules/ROOT/pages/opcodes/opcodes.adoc . I can convert the documentation to reStructuredText and create a PR to this repo if this issue is accepted.
The text was updated successfully, but these errors were encountered: