Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Rpc help helper class #14502
This should be helpful in few respects:
The new classes are in rpc/doc.cpp and they are added in the first commit
The second commit is the actual doc rewrite. The process of rewriting current docs to what is in the PR was semi-automatic - unfortunately, not automatic enough to make it a scripted diff. What I did:
It's still a huge chunk of code, even when it is just RPC help.
(Third commit is then removing the unused helper function.)
I think it does the same what @achow101 has been trying (by adding what I have in RPCDoc to UniValue instead) here https://github.com/achow101/bitcoin/tree/rpc-help-univ ; I did not use that because I did not fully understand how it was supposed to be working
This is a nice change, and I think making documentation more structured will make it easier to maintain.
I do think it'd be good to replace
That's a good point.
I used "Table" and "Row", since there are few more different table types, and also "Arguments" and "Results" tables are basically the same thing (Arguments have the numbers next to some rows, but only some of them)
The possible table types, by just grepping the source code:
All the Result subtypes are.... yeah basically the same thing, could be treated in some way.
Of course another level would be to somehow match the actual RPC arguments to the arguments in the table, and to the arguments in the short example in the first line, but that is ... just too complex. :)
Good first step would be to replace
This was referenced
Oct 20, 2018
Concept ACK. However, this seems to be a large change that is probably impossible to review without splitting it up in smaller chunks and/or making it a scripted diff.
While the change seems to touch every help text, it doesn't yet make it meaningfully easier to actually produce the help text machine-generated. You split out the rpc method name, but then pass all arguments as a single string and then each of them again as a "
Ideally we'd either merge some exhaustive fix similar to #14459 and then a pure scripted-diff to make it auto-generated (and check that the resulting documentation does not differ after the scripted-diff) or we do the auto-generation without the scripted diff and check that the resulting diff in the documentation looks similar to #14459.
I have quickly hacked up a first step of how I think here: #14530
Thanks for feedback.
ad script-diff: I can probably make it script-diffed, it will need some constistency fixed first so the text is parseable, but that can be done as a separate commit. (It is mostly whitespace, missing
ad other notes:
Yes, this PR lets most of the arguments/"rows" be as-is, as the various styles seemed too different to me to make consistent, so I gave up and just let it be; I focused mainly on getting rid of the "space-formatting" and making it automatically consistent.
If the goal is indeed to make generation of, for example, the first-line argument etc more automatic, that can be done, but will take more time :) but sure, it will be a nicer code
If I got it correctly. Let's say, walletfundedpsbt
The current RPC, at least start, is
Should the "subcodes" in inputs/outputs arguments, and their help, be also generated from some object (that seems to be m_inner in your example)? Including all the ",...." ? Should the first line stay like it is, or should it instead be
I am just saying it will be pretty hard to do this, that's why I opted for "just" adding
but if the goal is indeed to make all the doc even more uniform, it's probably better than this "naive" approach that just formats the spaces
edit: I look more closely at your #14530 and it indeed produces all the "pseudo-objects" on the left. OK