[doc] descriptor: explain GetPubKey() usage with cached public key

Sjors · Sjors · commit 2e68ffaf2058 · 2019-01-29T16:55:45.000+01:00
Plus a few typo fixes.
diff --git a/src/script/descriptor.cpp b/src/script/descriptor.cpp
@@ -207,9 +207,11 @@ class BIP32PubkeyProvider final : public PubkeyProvider
 /** Base class for all Descriptor implementations. */
 class DescriptorImpl : public Descriptor
 {
-    //! Public key arguments for this descriptor (size 1 for PK, PKH, WPKH; any size of Multisig).
+    //! Public key arguments for this descriptor (size 1 for PK, PKH, WPKH; any size for Multisig).
     const std::vector<std::unique_ptr<PubkeyProvider>> m_pubkey_args;
     //! The sub-descriptor argument (nullptr for everything but SH and WSH).
+    //! In doc/descriptors.m this is referred to as SCRIPT expressions sh(SCRIPT)
+    //! and wsh(SCRIPT), and distinct from KEY expressions and ADDR expressions.
     const std::unique_ptr<DescriptorImpl> m_subdescriptor_arg;
     //! The string name of the descriptor function.
     const std::string m_name;
@@ -295,6 +297,8 @@ class DescriptorImpl : public Descriptor
         // Construct temporary data in `entries` and `subscripts`, to avoid producing output in case of failure.
         for (const auto& p : m_pubkey_args) {
             entries.emplace_back();
+            // If we have a cache, we don't need GetPubKey to compute the public key.
+            // Pass in nullptr to signify only origin info is desired.
             if (!p->GetPubKey(pos, arg, cache_read ? nullptr : &entries.back().first, entries.back().second)) return false;
             if (cache_read) {
                 // Cached expanded public key exists, use it.
diff --git a/src/script/descriptor.h b/src/script/descriptor.h
@@ -46,17 +46,17 @@ struct Descriptor {
      *
      * pos: the position at which to expand the descriptor. If IsRange() is false, this is ignored.
      * provider: the provider to query for private keys in case of hardened derivation.
-     * output_script: the expanded scriptPubKeys will be put here.
+     * output_scripts: the expanded scriptPubKeys will be put here.
      * out: scripts and public keys necessary for solving the expanded scriptPubKeys will be put here (may be equal to provider).
-     * cache: vector which will be overwritten with cache data necessary to-evaluate the descriptor at this point without access to private keys.
+     * cache: vector which will be overwritten with cache data necessary to evaluate the descriptor at this point without access to private keys.
      */
     virtual bool Expand(int pos, const SigningProvider& provider, std::vector<CScript>& output_scripts, FlatSigningProvider& out, std::vector<unsigned char>* cache = nullptr) const = 0;
 
     /** Expand a descriptor at a specified position using cached expansion data.
      *
      * pos: the position at which to expand the descriptor. If IsRange() is false, this is ignored.
      * cache: vector from which cached expansion data will be read.
-     * output_script: the expanded scriptPubKeys will be put here.
+     * output_scripts: the expanded scriptPubKeys will be put here.
      * out: scripts and public keys necessary for solving the expanded scriptPubKeys will be put here (may be equal to provider).
      */
     virtual bool ExpandFromCache(int pos, const std::vector<unsigned char>& cache, std::vector<CScript>& output_scripts, FlatSigningProvider& out) const = 0;
