doc: Rework generate* doc #24137

MarcoFalke commented at 10:43 AM on January 24, 2022: member

Hide the test-only calls and clarify the short description

MarcoFalke commented at 11:05 AM on January 24, 2022: member

Rendered diff:

diff --git a/generateblock b/generateblock
index 55aca89..1fcd557 100644
--- a/generateblock
+++ b/generateblock
@@ -1,6 +1,6 @@
 generateblock "output" ["rawtx/txid",...]
 
-Mine a block with a set of ordered transactions immediately to a specified address or descriptor (before the RPC call returns)
+Mine a set of ordered transactions to a specified address or descriptor and return the block hash.
 
 Arguments:
 1. output               (string, required) The address or descriptor to send the newly generated bitcoin to.
diff --git a/generatetoaddress b/generatetoaddress
index 04c2092..6abb868 100644
--- a/generatetoaddress
+++ b/generatetoaddress
@@ -1,9 +1,9 @@
 generatetoaddress nblocks "address" ( maxtries )
 
-Mine blocks immediately to a specified address (before the RPC call returns)
+Mine to a specified address and return the block hashes.
 
 Arguments:
-1. nblocks     (numeric, required) How many blocks are generated immediately.
+1. nblocks     (numeric, required) How many blocks are generated.
 2. address     (string, required) The address to send the newly generated bitcoin to.
 3. maxtries    (numeric, optional, default=1000000) How many iterations to try.
 
diff --git a/generatetodescriptor b/generatetodescriptor
index cfbcf86..9572971 100644
--- a/generatetodescriptor
+++ b/generatetodescriptor
@@ -1,9 +1,9 @@
 generatetodescriptor num_blocks "descriptor" ( maxtries )
 
-Mine blocks immediately to a specified descriptor (before the RPC call returns)
+Mine to a specified descriptor and return the block hashes.
 
 Arguments:
-1. num_blocks    (numeric, required) How many blocks are generated immediately.
+1. num_blocks    (numeric, required) How many blocks are generated.
 2. descriptor    (string, required) The descriptor to send the newly generated bitcoin to.
 3. maxtries      (numeric, optional, default=1000000) How many iterations to try.

DrahtBot added the label Mining on Jan 24, 2022

DrahtBot added the label RPC/REST/ZMQ on Jan 24, 2022

MarcoFalke added the label Docs on Jan 24, 2022

MarcoFalke removed the label RPC/REST/ZMQ on Jan 24, 2022

MarcoFalke removed the label Mining on Jan 24, 2022

MarcoFalke added the label Tests on Jan 24, 2022

MarcoFalke removed the label Docs on Jan 24, 2022

MarcoFalke force-pushed on Jan 24, 2022

DrahtBot commented at 12:03 AM on January 25, 2022: member

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

Conflicts

Reviewers, this pull request conflicts with the following ones:

#24028 (doc: Explain in the generate* RPC docs that they are only for testing by sipa)
#18933 (rpc: Add submit option to generateblock by MarcoFalke)

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.

MarcoFalke added this to the milestone 23.0 on Jan 26, 2022

luke-jr changes_requested

luke-jr commented at 8:45 PM on January 29, 2022: member

Concept ACK, but I think it should keep the explicit mention of not returning until the blocks are mined.

MarcoFalke commented at 8:55 AM on January 30, 2022: member

It should be common sense that a hash of something can only be returned after it has been created (mined), so I am leaving this as-is for now

MarcoFalke commented at 10:01 AM on February 14, 2022: member

Also, the wording "immediately" isn't true. On testnets with difficulty higher than regtest, it may take a few iterations.

in src/rpc/mining.cpp:264 in fa763cf5da outdated

 271 | -                    RPCResult::Type::ARR, "", "hashes of blocks generated",
 272 | -                    {
 273 | -                        {RPCResult::Type::STR_HEX, "", "blockhash"},
 274 | -                    }},
 275 | -                RPCExamples{
 276 | +        "Mine to a specified descriptor and return the block hashes.",

achow101 commented at 7:47 PM on February 17, 2022:

s/descriptor/address

        "Mine to a specified address and return the block hashes.",

MarcoFalke commented at 7:59 AM on February 18, 2022:

Thanks, fixed

MarcoFalke force-pushed on Feb 18, 2022

in src/rpc/mining.cpp:305 in fa3bb584dc outdated

 301 | @@ -302,7 +302,7 @@ static RPCHelpMan generatetoaddress()
 302 |  static RPCHelpMan generateblock()
 303 |  {
 304 |      return RPCHelpMan{"generateblock",
 305 | -        "\nMine a block with a set of ordered transactions immediately to a specified address or descriptor (before the RPC call returns)\n",

0xB10C commented at 9:27 AM on February 21, 2022:

I'm not familiar with RPCHelpMan. Why can we drop the \n here and at the two other occurrences?

MarcoFalke commented at 9:51 AM on February 21, 2022:

Starting and trailing whitespace is normalized by RPCHelpMan. See also the rendered diff: #24137 (comment)

0xB10C commented at 9:42 AM on February 21, 2022: member

Code Review ACK fa3bb584dcc742a767b2141cd7324877e3cf5302

Only reviewed changes to the RPC docs via #24137 (comment).

bitcoin-cli -help lists -generate and says that it mines the blocks immediately. Could be changed there too.

  -generate
       Generate blocks immediately, equivalent to RPC getnewaddress followed by
       RPC generatetoaddress. Optional positional integer arguments are
       number of blocks to generate (default: 1) and maximum iterations
       to try (default: 1000000), equivalent to RPC generatetoaddress
       nblocks and maxtries arguments. Example: bitcoin-cli -generate 4
       1000

MarcoFalke force-pushed on Feb 21, 2022

MarcoFalke commented at 10:00 AM on February 21, 2022: member

Thanks, rebased and fixed up bitcoin-cli.cpp. Should be trivial to re-review with git range-diff bitcoin-core/master fa3bb584dc fa30e62cc6.

doc: Rework generate* doc

Can be reviewed with --word-diff-regex=. --ignore-all-space

fa30e62cc6

MarcoFalke force-pushed on Feb 21, 2022

0xB10C commented at 10:22 AM on February 21, 2022: member

reACK fa30e62cc609ff29f0acaa5047d3f437cb04a67b. changes since fa3bb584dcc742a767b2141cd7324877e3cf5302 are: dropping the immediately + formatting the touched line and a rebase

fanquake merged this on Feb 21, 2022

fanquake closed this on Feb 21, 2022

MarcoFalke deleted the branch on Feb 21, 2022

sidhujag referenced this in commit be6fb4454a on Feb 22, 2022

DrahtBot locked this on Feb 21, 2023