Issue #1865 - Clean up RPC help messages

sje1 commented at 11:58 am on October 29, 2013: contributor

Some expanded docs for the rpc commands…comments? terrible?

Based on the proposal, update the help message of rpc methods

strings arguments are in double quotes rather than square brackets
numeric arguments have no quotes (and no default value)
optional parameters are surrounded by round brackets
json arguments are strings but don’t use double quotes

Added 3 sections for the details

Arguments: lists each argument, it’s type, required or not, a default, and a description
Result: The method result, with json format if applicable, type, and a description
Examples: examples calls using bitcoin-cli and curl for json rpc call

Problems

maybe this is too verbose
lines might be too long
description are not good or complete
examples may be too much

Issue #1865 - Clean up RPC help messages

Based on the proposal, update the help message of rpc methods
- strings arguments are in double quotes rather than square brackets
- numeric arguments have no quotes (and no default value)
- optional parameters are surrounded by round brackets
- json arguments are strings but don't use double quotes

Added 3 sections for the details
- Arguments: lists each argument, it's type, required or not, a default, and a description
- Result: The method result, with json format if applicable, type, and a description
- Examples: examples calls using bitcoin-cli and curl for json rpc call

Problems
- maybe this is too verbose
- lines might be too long
- description are not good or complete
- examples may be too much

5c2734b7b9

laanwj commented at 12:30 pm on October 29, 2013: member

Looks good

in src/rpcblockchain.cpp: in 5c2734b7b9 outdated

 93@@ -88,7 +94,13 @@ Value getbestblockhash(const Array& params, bool fHelp)
 94     if (fHelp || params.size() != 0)
 95         throw runtime_error(
 96             "getbestblockhash\n"
 97-            "Returns the hash of the best (tip) block in the longest block chain.");
 98+            "\nReturns the hash of the best (tip) block in the longest block chain.\n"
 99+            "\nResult\n"
100+            "\"hex\"      (string) the block hash hex encoded\n"
101+            "\nExamples\n"
102+            "> bitcoin-cligetbestblockhash\n"

laanwj commented at 12:31 pm on October 29, 2013:

Missing a space here

laanwj commented at 12:33 pm on October 29, 2013: member

ACK, this is certainly an improvement over what is there

sipa commented at 2:45 pm on October 29, 2013: member

There seems to be a lot of duplication (the example command lines in particular). Mind moving the generation of those to a common method?

sje1 commented at 5:25 am on October 30, 2013: contributor

Thanks for the comments. I have done a few updates. I had done this on the 0.8.5 branch and tested the output, but haven’t been able to figure out how to build the head to verify it (on centos 5)

BitcoinPullTester commented at 5:43 am on October 30, 2013: none

Automatic sanity-testing: FAILED BUILD/TEST, see http://jenkins.bluematt.me/pull-tester/53b1b1ade8b4d6605fbf145bb62489627cecae68 for binaries and test log.

This could happen for one of several reasons:

It chanages paths in makefile.linux-mingw or otherwise changes build scripts in a way that made them incompatible with the automated testing scripts (please tweak those patches in qa/pull-tester)
It adds/modifies tests which test network rules (thanks for doing that), which conflicts with a patch applied at test time
It does not build on either Linux i386 or Win32 (via MinGW cross compile)
The test suite fails on either Linux i386 or Win32
The block test-cases failed (lookup the first bNN identifier which failed in https://github.com/TheBlueMatt/test-scripts/blob/master/FullBlockTestGenerator.java)

If you believe this to be in error, please ping BlueMatt on freenode or TheBlueMatt here.

This test script verifies pulls every time they are updated. It, however, dies sometimes and fails to test properly. If you are waiting on a test, please check timestamps to verify that the test.log is moving at http://jenkins.bluematt.me/pull-tester/current/ Contact BlueMatt on freenode if something looks broken.

Doc cleanup based on comments

The examples are generated from a common method (see bitcoinrpc.h).
This also fixes is missing space in rpcblockchain.cpp:101
Some other cleanup

53b1b1ade8

laanwj commented at 7:22 am on October 30, 2013: member

@sje1 what problem do you have building head on centos 5?

sje1 commented at 2:44 am on October 31, 2013: contributor

i was building 8.0.5 by building each dependency (boost, db, openssl), then setting the paths in the Makefile.

on centos 5, not sure how to update or install the latest autoconf

./autogen.sh configure.ac:2: error: Autoconf version 2.60 or higher is required

on centos 6, autoconf is ok, i couldn’t get it to use my boost but it worked with the built-in one, but key.cpp fails with lots of undefined references

key.cpp:184: undefined reference to `EC_KEY_set_conv_form'

laanwj commented at 2:05 pm on November 4, 2013: member

The key.cpp errors could have to do with Centos not including the ecc parts of OpenSSL? I remember there was the same issue with Fedora due to patents. Though this would be nothing new with autoconf.

Edit: But is this ready for merging otherwise?

sipa commented at 4:47 pm on November 4, 2013: member

Sounds like you’re building against a non-ECC OpenSSL build, indeed.

laanwj commented at 3:32 pm on November 6, 2013: member

You need to use fully qualified std::string in the .h file, hence the pull tester errors:

0In file included from noui.cpp:8:
1bitcoinrpc.h:155: error: ‘string’ was not declared in this scope
2bitcoinrpc.h:155: error: ‘string’ was not declared in this scope
3bitcoinrpc.h:156: error: ‘string’ was not declared in this scope
4bitcoinrpc.h:156: error: ‘string’ was not declared in this scope
5make[3]: *** [noui.o] Error 1

laanwj commented at 9:01 am on November 11, 2013: member

@sje1 any luck yet?

If not, mind if I take over this pull request and get it merged before other RPC changes?

laanwj commented at 1:55 pm on November 13, 2013: member

Continued in #3246

laanwj closed this on Nov 13, 2013

sje1 commented at 10:46 am on November 15, 2013: contributor

@laanwj thanks for taking over, i haven’t figured out how to build yet :)

Bushstar referenced this in commit 251fb5e69c on Apr 8, 2020

Bushstar referenced this in commit 66e298728e on Apr 8, 2020

DrahtBot locked this on Sep 8, 2021

Issue #1865 - Clean up RPC help messages #3184