Alternate structure for EIP documents

[davesque]

IIRC, @axic proposed a structure for ABI-related EIP documents like this:

• Basic format w/out tuple encoding
• Tuple (head-tail) encoding
• JSON interface format
• JSON test format

I feel like it might be difficult for library developers to have to cross-reference two EIPs to get a comprehensive picture of the encoding format. Therefore, I've wondered if it wouldn't make sense to structure the EIP documents in the following way:

• Comprehensive, formal definition of ABI encoding
• Supplementary discussion of encoding format
• JSON interface format
• JSON test format

The formal definition document could give a terse, mathematical description of the format. Another supplementary document could discuss the implications or finer points of that definition. The other two documents would just be the same as before.

Thoughts on this?

[davesque]

If we determine, as in #2 , that this isn't the right place for this kind of discussion, we can just close this issue.

[davesque]

One of the motivations behind this idea is that I'm finding it a bit hard to reliably separate the description of static (basic) ABI types and the description of dynamic ABI types and the head-tail encoding along with tuples and arrays. For example, early on in the current Solidity docs there is a section that describes function selector construction. Since it's natural to also discuss function argument encoding in that context, a section on that topic follows the function selector section.

Now, let's imagine we split the tuple encoding section out into a separate document. Wouldn't it also make sense to remove the argument encoding section? After all, you can't correctly encode a function's arguments (even assuming you're not using any tuples or arrays) without the head-tail encoding since the arguments might include a bytes or string value. Those values are dynamic and would need to be head-tail encoded.

So then it seems to me that, if we really want to separate out the tuple encoding stuff in a non-confusing manner, we'd have to remove quite a few sections from the current Solidity docs. Then I'm left to question whether or not a standalone document that discusses only the basic types in the Solidity ABI is really worth that much. In other words, why would anyone really ever only be interested in a document that discusses only the basic types? It seems like you wouldn't be able to do much with it.