From 1388de83900eaced906d369fe9e8887ae74b2dcf Mon Sep 17 00:00:00 2001
From: Jon Atack <jon@atack.com>
Date: Sun, 27 Oct 2019 14:16:00 +0100
Subject: rpc: add getaddressinfo code documentation

and separate the fields with a line break for readability.
---
 src/wallet/rpcwallet.cpp | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

(limited to 'src')

diff --git a/src/wallet/rpcwallet.cpp b/src/wallet/rpcwallet.cpp
index 9dd7d8435c..f4b5a8b9ac 100644
--- a/src/wallet/rpcwallet.cpp
+++ b/src/wallet/rpcwallet.cpp
@@ -3778,23 +3778,39 @@ UniValue getaddressinfo(const JSONRPCRequest& request)
 
     CScript scriptPubKey = GetScriptForDestination(dest);
     ret.pushKV("scriptPubKey", HexStr(scriptPubKey.begin(), scriptPubKey.end()));
+
     const SigningProvider* provider = pwallet->GetSigningProvider(scriptPubKey);
 
     isminetype mine = pwallet->IsMine(dest);
     ret.pushKV("ismine", bool(mine & ISMINE_SPENDABLE));
+
     bool solvable = provider && IsSolvable(*provider, scriptPubKey);
     ret.pushKV("solvable", solvable);
+
     if (solvable) {
        ret.pushKV("desc", InferDescriptor(scriptPubKey, *provider)->ToString());
     }
+
     ret.pushKV("iswatchonly", bool(mine & ISMINE_WATCH_ONLY));
+
+    // Return DescribeWalletAddress fields.
+    // Always returned: isscript, ischange, iswitness.
+    // Optional: witness_version, witness_program, script, hex, pubkeys (array),
+    // sigsrequired, pubkey, embedded, iscompressed.
     UniValue detail = DescribeWalletAddress(pwallet, dest);
     ret.pushKVs(detail);
+
+    // Return label field if existing. Currently only one label can be
+    // associated with an address, so the label should be equivalent to the
+    // value of the name key/value pair in the labels hash array below.
     if (pwallet->mapAddressBook.count(dest)) {
         ret.pushKV("label", pwallet->mapAddressBook[dest].name);
     }
+
     ret.pushKV("ischange", pwallet->IsChange(scriptPubKey));
 
+    // Fetch KeyMetadata, if present, for the timestamp, hdkeypath, hdseedid,
+    // and hdmasterfingerprint fields.
     ScriptPubKeyMan* spk_man = pwallet->GetScriptPubKeyMan(scriptPubKey);
     if (spk_man) {
         if (const CKeyMetadata* meta = spk_man->GetMetadata(dest)) {
@@ -3807,9 +3823,11 @@ UniValue getaddressinfo(const JSONRPCRequest& request)
         }
     }
 
-    // Currently only one label can be associated with an address, return an array
-    // so the API remains stable if we allow multiple labels to be associated with
-    // an address.
+    // Return a labels array containing a hash of key/value pairs for the label
+    // name and address purpose. The name value is equivalent to the label field
+    // above. Currently only one label can be associated with an address, but we
+    // return an array so the API remains stable if we allow multiple labels to
+    // be associated with an address in the future.
     UniValue labels(UniValue::VARR);
     std::map<CTxDestination, CAddressBookData>::iterator mi = pwallet->mapAddressBook.find(dest);
     if (mi != pwallet->mapAddressBook.end()) {
-- 
cgit v1.2.3