copying from the PR description:
Note: There doesn’t appear to be any RPC-friendly API documentation standard, otherwise I’d be open to using that over markdown. Still, this EIP is meant to provide a human-readable RPC specification and isn’t necessarily meant to be program-readable or to drive other documentation tooling (though the markdown itself could drive tooling if desired).
My expectation is that if the RPC specification is only human readable, then it will quickly become outdated just like the current wiki. A human-readable spec relies on volunteers (client developers and users) to update the documentation, which is a laborious burden that people tend to grow tired of.
As a solution, I proposed a machine-readable spec (Universal specs for JSON-RPC API methods · Issue #217 · ethereum/EIPs · GitHub), and kickstarted the effort with a multi-client testrunner and proof-of-concept compatibility table: Ethereum client compatibility table
It was recently dusted off and run again on the the latest clients: run rpc-compat on the latest clients · Issue #119 · ethereum/hive · GitHub
Here’s a screenshot of the table:
It only has the JSON schema specs for a handful of rpc methods, so the main remaining todo is to add the rest. Additionally, I was planning to the description field in the json schema to auto-generate the wiki documentation. This way we would not be relying on volunteers to keep the documentation up to date. Rather, the testrunner automatically checks which clients are compatible with the spec, and the human-readable documentation is generated from the spec.