rpc help helper class #14378

1. 
   MarcoFalke commented at 4:30 am on October 3, 2018: member

   The rpc help (documentation) is currently manually updated with no checks of correctness or consistency with the code.

   I think the goal should be that the rpc help is generated by pretty printing a cpp object (as opposed to the hardcoded string)

   In a first step, the constructor of the class could just take the name of the method, and an array of args. Each arg would be a json value (c.f. https://gist.github.com/karel-3d/1490786786525b0365ea8f459a9fc683#examples-1) with the type and the name to be used when calling with named arguments. Also, each arg would have flags for optional/required (and a default for non-required args), as well as a short description string.

   Further enhancements would be to do the same for the result (returned json) and finally to check the types provided in the documentation against the types passed during runtime.

2. MarcoFalke added the label RPC/REST/ZMQ on Oct 3, 2018
3. MarcoFalke added the label good first issue on Oct 3, 2018
4. MarcoFalke added the label Hacktoberfest on Oct 3, 2018
5. 
   karelbilek commented at 7:51 am on October 5, 2018: contributor

   I have only now found out this issue and your PR

   I have made a separate issue here

   #14399

   (the link to my gist doesn’t work now, I have removed the examples)

   If you make a helper class, the results of the parser can probably be directly used (with some changes - removing the markdown=>html converter for example).

   I have misread your comment; you seem to want to use the actual arguments and results in the code. Which is more complex.

6. 
   MarcoFalke commented at 8:00 am on October 5, 2018: member

   Indeed, you could just teach the helper class to export in md or html or whatever instead of our internal format.
7. 
   achow101 commented at 9:10 am on October 5, 2018: member

   I’ve been working on a helper class for this but has turned out to be more complicated than I expected. I hope to get a pr for it out in a few days.
8. 
   karelbilek commented at 9:42 am on October 5, 2018: contributor

   If it helps, I made slight change to the parser and exported the RPC to JSON, with the structure logic of the proposal

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

   I have misread your comment; you seem to want to use the actual arguments and results. Which is more complex and this will not help that much

9. 
   etscrivner commented at 3:39 pm on October 5, 2018: contributor

   Put together a small prototype for this using a builder interface here. A small example is below:

   0auto docs = RPCDocumentation("getrawmempool")
   1  .DescriptionLine("Returns all transaction ids in memory pool as a json array of string transaction ids.")
   2  .DescriptionLine("Hint: use getmempoolentry to fetch a specific transaction from the mempool.")
   3  .Argument("first", "integer", "The first argument is required", true)
   4  .Argument("verbose", "boolean", "True for json object, false for array of transaction ids", false, "false")
   5  .Argument("other", "string", "Another argument");
   

   You can then generate docs as follows:

   0std::cout << docs.write()
   

   The result looks as follows:

   0getrawmempool first ( verbose "other" )
   1Returns all transaction ids in memory pool as a json array of string transaction ids.
   2
   3Hint: use getmempoolentry to fetch a specific transaction from the mempool.
   4
   5Arguments:
   61. first (integer) The first argument is required
   72. verbose (boolean, optional, default=false) True for json object, false for array of transaction ids
   83. other (string, optional) Another argument
   

   While this is only a small first step, curious if this is what @MarcoFalke had in mind or something different?

10. 
    karelbilek commented at 4:38 pm on October 5, 2018: contributor

    Just a note - some of the RPCs have very wild docs in the input arguments.

    See fundrawtransaction for example

    https://bitcoincore.org/en/doc/0.16.0/rpc/rawtransactions/fundrawtransaction/

11. 
    achow101 commented at 10:44 pm on October 5, 2018: member

    Ideally the helper class should be able to work for handling the help for JSON formatted arguments and results. IMO such a helper is most useful for formatting the results as those are usually the things that have the most indentation and whitespace issues as they are typically large JSON things.

    I’ve begun working on this here: https://github.com/achow101/bitcoin/tree/rpc-help-univ.

12. 
    karelbilek commented at 4:56 pm on October 14, 2018: contributor

    @etscrivner I got inspired by your gist and I edited a little to match what I actually found in the RPC docs and how the RPC docs look like

    https://gist.github.com/karel-3d/5847ea0172350368dead323211893faa

    I will try to actually add that to bitcoin source code soon-ish and make a PR.

    (By looking in the source code, I found out I missed a lot of “hidden” RPCs in all the extraction scripts. I didn’t even know they exist!)

13. MarcoFalke removed the label Hacktoberfest on Oct 20, 2018
14. MarcoFalke removed the label good first issue on Oct 20, 2018
15. MarcoFalke referenced this in commit c651265c93 on Nov 13, 2018
16. 
    domob1812 commented at 6:57 am on November 19, 2018: contributor

    FYI, Namecoin already uses a class with a fluent interface (similar to what @etscrivner suggested above) to build some help texts, altough in a particularly repetetive setting.
17. 
    MarcoFalke commented at 3:03 pm on November 19, 2018: member

    Looks like that doesn’t work with types. I.e. you’d still have to manually stringify the type name and adjust the formatting based on the type.

    https://github.com/namecoin/namecoin-core/blob/db0bcba13273d5b83d80cb8077861ae8744f80bb/src/rpc/names.cpp#L378-L380

    Also, it doesn’t work with pretty printing dictionaries or arrays:

    https://github.com/namecoin/namecoin-core/blob/db0bcba13273d5b83d80cb8077861ae8744f80bb/src/rpc/names.cpp#L357-L359

18. 
    domob1812 commented at 3:10 pm on November 19, 2018: contributor

    Well, that’s just what the code is at the moment (in case that wasn’t clear, I wrote it). The main goal for it was to just simplify some part of the formatting that was particularly repetetive. The interface can surely be extended (and adapted for Bitcoin) to pretty print dictionaries and other things more nicely.
19. MarcoFalke closed this on Dec 6, 2018

    ---

20. 
    karelbilek commented at 8:32 am on December 7, 2018: contributor

    great work
21. 
    jnewbery commented at 9:06 pm on December 10, 2018: member

    This was closed by #14796
22. pravblockc referenced this in commit 04b9a0f23e on Aug 10, 2021
23. pravblockc referenced this in commit ae8fa4c837 on Aug 10, 2021
24. pravblockc referenced this in commit 01792247fe on Aug 11, 2021
25. pravblockc referenced this in commit ac9f466e55 on Aug 11, 2021
26. pravblockc referenced this in commit 976d54f284 on Aug 12, 2021
27. pravblockc referenced this in commit 1a1378b96f on Aug 12, 2021
28. DrahtBot locked this on Sep 8, 2021

Contributors
MarcoFalke karelbilek achow101 etscrivner domob1812 jnewbery

Labels
RPC/REST/ZMQ