Document RPC method aliasing

ryanofsky · ryanofsky · commit 4c317d89e9d9 · 2018-03-15T16:37:57.000-04:00
Suggested by Sjors Provoost <sjors@sprovoost.nl> in bitcoin#11536 (comment)
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
@@ -710,3 +710,14 @@ A few guidelines for introducing and reviewing new RPC interfaces:
     client may be aware of prior to entering a wallet RPC call, we must block
     until the wallet is caught up to the chainstate as of the RPC call's entry.
     This also makes the API much easier for RPC clients to reason about.
+
+- Be aware of RPC method aliases and generally avoid registering the same
+  callback function pointer for different RPCs.
+
+  - *Rationale*: RPC methods registered with the same function pointer will be
+    considered aliases and only the first method name will show up in the
+    `help` rpc command list.
+
+  - *Exception*: Using RPC method aliases may be appropriate in cases where a
+    new RPC is replacing a deprecated RPC, to avoid both RPCs confusingly
+    showing up in the command list.
diff --git a/src/rpc/server.h b/src/rpc/server.h
@@ -165,8 +165,17 @@ class CRPCTable
 
     /**
      * Appends a CRPCCommand to the dispatch table.
+     *
      * Returns false if RPC server is already running (dump concurrency protection).
+     *
      * Commands cannot be overwritten (returns false).
+     *
+     * Commands with different method names but the same callback function will
+     * be considered aliases, and only the first registered method name will
+     * show up in the help text command listing. Aliased commands do not have
+     * to have the same behavior. Server and client code can distinguish
+     * between calls based on method name, and aliased commands can also
+     * register different names, types, and numbers of parameters.
      */
     bool appendCommand(const std::string& name, const CRPCCommand* pcmd);
 };
