Github user Jens-G commented on the issue: https://github.com/apache/thrift/pull/1036 Overall pretty neat. I still have a few complaints. 1. The document repeats a lot of stuff that can be found elsewhere, e.g. in the Thrift Whitepaper. There is nothing per se wrong with repeating stuff, but from my feeling it makes the spec a bit bloaty. 2. I think the structure should be revised grossly. No need to panic, I'm going to explain what I have in mind. By looking at the bits and bytes the reader may miss an important point: The order of data is always the same and entitrely Independent from the wire format, because that's the way Thrift Protocols work. * At the first level we have messages. They have a certain structure. * at the next level, a particular data item has a certain structure: a map always consists of two types and a count, plus the elements. That does not change between protocols. What changes is the way how a particular protocol organizes the data onto the wire. * and one level deeper we are at what I mean by revising the structure: I would not constantly jump back and forth between protocols to explain structs, lists, sets, integers, etc. Instead, there should be one chapter focusing on binary, and another one for compact. That makes it much easier a) for the reader who is usually interested in only one protocol at a time, and b) for future maintainers to add more protocols, such as JSON.
--- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. ---