Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rpc: Document default values for optional arguments #14877

Merged
merged 1 commit into from Dec 10, 2018

Conversation

@MarcoFalke
Copy link
Member

@MarcoFalke MarcoFalke commented Dec 5, 2018

No description provided.

@DrahtBot
Copy link
Contributor

@DrahtBot DrahtBot commented Dec 5, 2018

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

  • #14707 ([RPC] Include coinbase transactions in receivedby RPCs by andrewtoth)
  • #14641 (rpc: Add min_conf option to fund transaction calls by promag)
  • #11413 ([wallet] [rpc] sendtoaddress/sendmany: Add explicit feerate option by kallewoof)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

src/rpc/rawtransaction.cpp Outdated Show resolved Hide resolved
src/rpc/rawtransaction.cpp Outdated Show resolved Hide resolved
src/rpc/rawtransaction.cpp Outdated Show resolved Hide resolved
@MarcoFalke MarcoFalke force-pushed the Mf1812-rpcDefault branch from eeee62f to fadea91 Dec 6, 2018
@MarcoFalke
Copy link
Member Author

@MarcoFalke MarcoFalke commented Dec 6, 2018

Thanks @practicalswift. Fixed my language

@@ -888,9 +888,9 @@ static UniValue estimaterawfee(const JSONRPCRequest& request)
"defined in BIP 141 (witness data is discounted).\n",
{
{"conf_target", RPCArg::Type::NUM, /* opt */ false, /* default_val */ "", "Confirmation target in blocks (1 - 1008)"},
{"threshold", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "The proportion of transactions in a given feerate range that must have been\n"
{"threshold", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "0.95", "The proportion of transactions in a given feerate range that must have been\n"
Copy link
Contributor

@jonasschnelli jonasschnelli Dec 9, 2018

what about using a stringprint of the threshold variable?

@jonasschnelli
Copy link
Contributor

@jonasschnelli jonasschnelli commented Dec 9, 2018

utACK fa0c24c
Somehow I would be in favour of putting brackets around descriptive values ((null) instead of null and (fallback to nodeid) instead of fallback to nodeid) to avoid confusion between real default values and behavioural description.

@kristapsk
Copy link
Contributor

@kristapsk kristapsk commented Dec 10, 2018

ACK fa0c24c

Copy link
Contributor

@ryanofsky ryanofsky left a comment

ACK fa0c24c. I checked help output using the hack from #14726 (review)

This is a nice documentation change. If you wanted to follow up with more improvements I have some suggestions below:

  • The fallback descriptions like "fallback to wallet's default" are vague and could be described in more detail.
  • I don't think saying (default=null) or (default=omitted) is ever helpful. Just because of the way we check arguments, omitting an argument is always equivalent to passing null. And (default=omitted) is just a tautology. The point of the default documentation should be to say what an RPC call will do when an argument is null or omitted. I actually think it would be better to drop the all the (default=null) and (default=omitted) strings if they can't be replaced with something more constructive, to avoid creating a bad precedent for future changes.

{"bantime", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "", "time in seconds how long (or until when if [absolute] is set) the IP is banned (0 or empty means using the default time of 24h which can also be overwritten by the -bantime startup argument)"},
{"absolute", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "", "If set, the bantime must be an absolute timestamp in seconds since epoch (Jan 1 1970 GMT)"},
{"bantime", RPCArg::Type::NUM, /* opt */ true, /* default_val */ "0", "time in seconds how long (or until when if [absolute] is set) the IP is banned (0 or empty means using the default time of 24h which can also be overwritten by the -bantime startup argument)"},
{"absolute", RPCArg::Type::BOOL, /* opt */ true, /* default_val */ "false", "If set, the bantime must be an absolute timestamp in seconds since epoch (Jan 1 1970 GMT)"},
Copy link
Contributor

@ryanofsky ryanofsky Dec 10, 2018

/If set/If true/ might be more accurate

@kristapsk
Copy link
Contributor

@kristapsk kristapsk commented Dec 10, 2018

I don't think saying (default=null) or (default=omitted) is ever helpful. (...) I actually think it would be better to drop the all the (default=null) and (default=omitted) strings if they can't be replaced with something more constructive, to avoid creating a bad precedent for future changes.

If there is "default=" string outputted for each optional argument, functional test could be made that checks that people don't forget to document optional argument defaults for a new RPCs.

@ryanofsky
Copy link
Contributor

@ryanofsky ryanofsky commented Dec 10, 2018

If there is "default=" string outputted for each optional argument, functional test could be made that checks that people don't forget to document optional argument defaults for a new RPCs.

IMO, better to write that test with a list of exceptions for grandfathered, undocumented default arguments, than to leave bad documentation scattered over the codebase, especially since existing documentation is often used as a template for new documentation

@kristapsk
Copy link
Contributor

@kristapsk kristapsk commented Dec 10, 2018

Oh, yes, short list of a few exceptions probably is better idea.

@MarcoFalke
Copy link
Member Author

@MarcoFalke MarcoFalke commented Dec 10, 2018

I have changes piled up locally to enforce that it is either a required arg or a default value is provided at compile time.

@MarcoFalke MarcoFalke merged commit fa0c24c into bitcoin:master Dec 10, 2018
2 checks passed
MarcoFalke added a commit that referenced this issue Dec 10, 2018
fa0c24c rpc: Document default values for optional arguments (MarcoFalke)

Pull request description:

Tree-SHA512: e1f5ea67d7ac67526ae87bffaeb308a9ad68632e161fe0148cd431a340bb7a30def18f1dbc7e98c6c1c269ac8942fd5d5334c85c48e4fb1cead70a42536b6eef
@MarcoFalke MarcoFalke deleted the Mf1812-rpcDefault branch Dec 10, 2018
@ryanofsky
Copy link
Contributor

@ryanofsky ryanofsky commented Dec 10, 2018

@MarcoFalke what do you want to do with all the (default=null) / (default=omitted) cruft? Do you want to address it in a future PR or maybe mark this one up for grabs so someone else can fill in useful default values?

@MarcoFalke
Copy link
Member Author

@MarcoFalke MarcoFalke commented Dec 10, 2018

@ryanofsky Your suggestion is a one-line change after #14918, so either you leave feedback there or create a pull request after #14918 is merged.

MarcoFalke added a commit that referenced this issue Jan 30, 2019
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: #7061 (comment)

  I already added the default values in #14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
deadalnix added a commit to Bitcoin-ABC/bitcoin-abc that referenced this issue May 22, 2020
Summary: This is a backport of Core [[bitcoin/bitcoin#14877 | PR14877]]

Test Plan:
  ninja all check-all

Reviewers: #bitcoin_abc, Fabien

Reviewed By: #bitcoin_abc, Fabien

Subscribers: Fabien

Differential Revision: https://reviews.bitcoinabc.org/D6218
Munkybooty added a commit to Munkybooty/dash that referenced this issue Aug 21, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
Munkybooty added a commit to Munkybooty/dash that referenced this issue Aug 23, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
Munkybooty added a commit to Munkybooty/dash that referenced this issue Aug 24, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
Munkybooty added a commit to Munkybooty/dash that referenced this issue Aug 24, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
Munkybooty added a commit to Munkybooty/dash that referenced this issue Aug 24, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
UdjinM6 added a commit to UdjinM6/dash that referenced this issue Aug 24, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
Munkybooty added a commit to Munkybooty/dash that referenced this issue Aug 24, 2021
fa5e6ef wallet: Fixup rescanblockchain result doc (MarcoFalke)

Pull request description:

  This was probably accidentally added to the wrong line when addressing the feedback here: bitcoin#7061 (comment)

  I already added the default values in bitcoin#14877, but it could be clarified more that this really has no specific block height as default value, since the tip can change during a rescan.

Tree-SHA512: 48a3c5143e2b7129ee8f396d2e77550cb393fbe45f5936aeebeb7a201d61560336a3ae47b26bb757a4dbbe217e06abfd67a5a673aef266b6c4d7a80d049a2b49
@bitcoin bitcoin locked as resolved and limited conversation to collaborators Sep 8, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants