Document the instruction format.

[ericsnowcurrently]

The code emitted by the compiler, stored in PyCodeObject.co_code, and executed in the eval loop clearly has a well-defined format. In 2016 (bpo-26647) we switched to a fixed size wordcode (16 bits). There are a number of details about that format which aren't obvious, nor easy to discover (especially for someone new to the code).

Consequently, it would be helpful to have the format documented (in an easily discovered location). I haven't been able to find anything like that, other than a few scattered comments in the code (in relatively non-obvious places). We have similar documentation in .txt files in the Objects dir (e.g. dictnotes.txt). Something like that would make sense to me. Likewise we have comments with a similar utility in various source and header files (e.g. Objects/odictobject.c,). Another option might be to put it in the devguide, though it would probably be better to keep it in the repo, tied to the implementation it describes.

(FYI, this issue was born of discussion on one of my PRs.)

[gvanrossum]

Isn’t this described under the ‘dis’ module?

[ericsnowcurrently]

It has some of the info though I was thinking of a bit more depth of technical detail.

[gvanrossum]

Okay, then we should put this in the source repo, not the dev guide. Are you volunteering? :-)

[ericsnowcurrently]

I'd be glad to do it. 🙂

[markshannon]

Is this going to happen?