ethereum
Add docstrings to all opcodes in the `Opcodes` Enum
It would be nice to have some docstrings with descriptions of each Opcode in the Opcodes Enum.
The docstring could have some nicely formatted description that includes at least the following information:
- Small description of the opcode behavior
- Parameters description
- Output description
- Fork when it was introduced
- Gas usage description
The docstrings are normally picked up by the IDE, such as vscode, and it's a nice and handy way to have the parameters show up when going through the code as a reminder of the parameters and whatnot.
please lmk if this format looks okay-ish or something needs to be changed(so I can replicate this with every opcode)
STOP = Opcode(0x00)
"""
Behavior: Halts execution
Input:
Output:
Was introduced in: Frontier
Gas: 0
"""
ADD = Opcode(0x01, popped_stack_items=2, pushed_stack_items=1)
"""
Behavior: Addition operation
Input: a: first integer value to add
b: second integer value to add
Output: a + b: integer result of the addition modulo 2**256
Was introduced in: Frontier
Gas: 3
"""
I took a look at how vscode renders the docstrings, and made some changes:
ADD = Opcode(0x01, popped_stack_items=2, pushed_stack_items=1)
"""
ADD(a, b) = c
----
Description
----
Addition operation
Inputs
----
- a: first integer value to add
- b: second integer value to add
Outputs
----
- c: integer result of the addition modulo 2**256
Fork
----
Frontier
Gas
----
3
"""
I think for other opcodes that are not arithmetic, e.g. CREATE, we can name the inputs and outputs gas, to, etc, instead of a, b, c ...
edit: Added hyphens to the inputs and outputs for it to better render in the documentation
Hey @ThreeHrSleep! Nice to have you here.
If you're keen, I wondered if a script could do a one-time pull of the doc from https://www.evm.codes?
Here's the doc for ADD in their repo.
After a quick check, it seems that if an opcode's functionality was modified in a subsequent fork, the additional information is documented in a a sub-folder, e.g., checkout https://github.com/smlxl/evm.codes/tree/main/docs/opcodes/55 (a complicated example). The additional info relevant for the latest fork could be added manually though.
We could also add a link at the bottom of the docstring directly to the opcode on evm.codes, e.g. (as above in https://github.com/ethereum/execution-spec-tests/issues/383#issuecomment-1917573084), but with:
Source: [evm.codes/#01](https://www.evm.codes/#01).
Thank you so much for the suggestion @danceratopz ! On it (very sorry for taking so long :sweat_smile: )