RPC unified format proposal #14399

1. 
   karelbilek commented at 7:49 am on October 5, 2018: contributor

   I have played with the RPC documents and I found out that while the format looks crazy, with some changes, it can be made easily parseable and I actually wrote a parser for that.

   I have wrote a proposal for a unified format, that requires minimal changes to the current docs (mostly whitespace), and a parser in go

   The proposal is here

   https://gist.github.com/karel-3d/1490786786525b0365ea8f459a9fc683

   The parser in go is here

   https://github.com/karel-3d/bitcoincore.org/blob/formatted_doc/contrib/doc-gen/convert.go

   (I found off-by-one error; the first example always has a description “Examples:”, please ignore that)

   The changes needed in bitcoin core are here

   https://github.com/karel-3d/bitcoin/commit/45d2c866b536b30b09b658d8b954c4a7bc820405

   And the result is generated here

   https://bitcoin-rpc.github.io/en/doc/0.17.99/rpc/wallet/sendmany/ (the repo here https://github.com/bitcoin-rpc/bitcoin-rpc.github.io but it’s just the _site from the jekyll)

   I want to first hear some general notes before posting a PR.

2. 
   karelbilek commented at 8:05 am on October 5, 2018: contributor

   It’s not easy to write an actual linter on this though.

   For example, if the type / description is not separated by two spaces properly, then the whole line is interpreted as pseudocode. But that’s still legal.

   I can maybe add rule that the pseudocode can’t be too long?

3. 
   karelbilek commented at 9:43 am on October 5, 2018: contributor

   This is when I export it to JSON, not to jekyll templates (slight change in code)

   https://gist.github.com/karel-3d/02f8143b8fd463f8fd2b74a9044614c1

4. fanquake added the label RPC/REST/ZMQ on Oct 5, 2018
5. 
   ch4ot1c commented at 8:12 pm on October 7, 2018: contributor

   • Typo: https://github.com/karel-3d/bitcoin/commit/45d2c866b536b30b09b658d8b954c4a7bc820405#diff-a0c8f511d90e83aa9b5857e819ced344R2044

   • We should try eliminate the multi-space tabs in the json. Although I do like your solution for simplicity.

   • I dislike the difference in Numeric/Bool and String types’ “example” formatting: https://gist.github.com/karel-3d/02f8143b8fd463f8fd2b74a9044614c1#file-rpc-json-L73 ; I wish we could make them all without quotes, and alert the user to use quotes for Strings externally. Maybe the pseudocode portion could be an external file/module, linked by rpc name.

   Nice work!

6. 
   karelbilek commented at 12:33 pm on October 24, 2018: contributor

   Closing this, better way is to do similar to this PR instead

   https://github.com/bitcoin/bitcoin/pull/14530

7. karelbilek closed this on Oct 24, 2018

   ---

8. DrahtBot locked this on Sep 8, 2021

Contributors
karelbilek ch4ot1c

Labels
RPC/REST/ZMQ