Add docstrings to all opcodes in the Opcodes Enum

[marioevz]

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.

[ThreeHrSleep]

hey ! can I work on this issue?

[marioevz]

hey ! can I work on this issue?

Of course!

[ThreeHrSleep]

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

[marioevz]

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

[ThreeHrSleep]

Thanks a lot for the feedback! making a PR as soon as I'm done :)

[danceratopz]

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 #383 (comment)), but with:

Source: [evm.codes/#01](https://www.evm.codes/#01).

[ThreeHrSleep]

Thank you so much for the suggestion @danceratopz !
On it
(very sorry for taking so long 😅 )

[ThreeHrSleep]

update: almost done,will make a PR by tonight