From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from sog-mx-3.v43.ch3.sourceforge.com ([172.29.43.193] helo=mx.sourceforge.net) by sfs-ml-1.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1YNnAQ-0003lx-1O for bitcoin-development@lists.sourceforge.net; Tue, 17 Feb 2015 18:46:42 +0000 X-ACL-Warn: Received: from relay3-d.mail.gandi.net ([217.70.183.195]) by sog-mx-3.v43.ch3.sourceforge.com with esmtps (TLSv1:AES256-SHA:256) (Exim 4.76) id 1YNnAO-0000ZK-OO for bitcoin-development@lists.sourceforge.net; Tue, 17 Feb 2015 18:46:42 +0000 Received: from mfilter12-d.gandi.net (mfilter12-d.gandi.net [217.70.178.129]) by relay3-d.mail.gandi.net (Postfix) with ESMTP id 50ADAA80D0; Tue, 17 Feb 2015 19:46:34 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mfilter12-d.gandi.net Received: from relay3-d.mail.gandi.net ([217.70.183.195]) by mfilter12-d.gandi.net (mfilter12-d.gandi.net [10.0.15.180]) (amavisd-new, port 10024) with ESMTP id RZemUo-28tzY; Tue, 17 Feb 2015 19:46:17 +0100 (CET) X-Originating-IP: 10.58.1.142 Received: from webmail.gandi.net (unknown [10.58.1.142]) (Authenticated sender: dario.teixeira@nleyten.com) by relay3-d.mail.gandi.net (Postfix) with ESMTPA id 6AEE4A80BC; Tue, 17 Feb 2015 19:46:17 +0100 (CET) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Date: Tue, 17 Feb 2015 18:46:17 +0000 From: Dario Teixeira To: "David A. Harding" In-Reply-To: <20150217155011.GA5124@localhost.localdomain> References: <9ec9df3b0ecb854fa19bd9100ed87d85@nleyten.com> <20150217155011.GA5124@localhost.localdomain> Message-ID: <8e6661f5abc99f6b93787a1e6f34e965@nleyten.com> X-Sender: dario.teixeira@nleyten.com User-Agent: Roundcube Webmail/0.9.5 X-Spam-Score: 0.0 (/) X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. X-Headers-End: 1YNnAO-0000ZK-OO Cc: bitcoin-development@lists.sourceforge.net Subject: Re: [Bitcoin-development] More precise type information in API reference X-BeenThere: bitcoin-development@lists.sourceforge.net X-Mailman-Version: 2.1.9 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 Feb 2015 18:46:42 -0000 Hi Dave, > I'm the primary author of the Bitcoin.org JSON-RPC reference, and I'd > be happy to help. Thanks -- it is much appreciated! > Do you think it would be possible for you to submit a minimal pull > request against the docs adding the type information you need to just > one RPC call? From there we can see how much work it would take to > generalize that across all 100+ printed pages worth of RPC docs. Sure, I would be glad to help. In fact, most of grunt work has already been done for the OCaml-bitcoin API [1,2], which could be used as a guide even if you don't use OCaml (beware that it may contain errors, though). Besides tweaking each RPC call, we would need to add a new section to the docs, to be placed before the RPC calls. This List of Types section would list all the custom types defined in the API, providing a brief description for each and indicating the JSON type used for serialisation (almost invariantly "string", I reckon). But before I submit a pull request, allow me to exemplify with AddMultiSigAddress: Parameter #1: (no changes) Parameter #2: I would keep "array" as the type of "Keys or Addresses". If we follow the convention of using a pipe character to represent unions, then the type for "Key or Address" is not "string", but "public_key | p2pkh_address". This would also require adding two entries to the List of Types section, describing public_key and p2pkh_address, and letting the users know that they are serialised as JSON strings. (Note that the precise type of "Keys or Addresses" is actually "Array [public_key | p2pkh_address]". However, since the type of each element is also listed, this info is redundant and we can safely state it's just an array.) Parameter #3: The type should be "account", obviously. Result: a p2sh_address. If there is only one type of such P2SH addresses and they can be used interchangeably, then this would suffice. If however, there are actually several incompatible kinds of P2SH address, then we'd need to be more precise about which one we mean. Thanks again for your time! Kind regards, Dario Teixeira [1] http://ocaml-bitcoin.forge.ocamlcore.org/apidoc/Bitcoin.ENGINE.html [2] http://ocaml-bitcoin.forge.ocamlcore.org/apidoc/Bitcoin.html