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 <dario.teixeira@nleyten.com>
To: "David A. Harding" <dave@dtrt.org>
In-Reply-To: <20150217155011.GA5124@localhost.localdomain>
References: <9ec9df3b0ecb854fa19bd9100ed87d85@nleyten.com>
	<cc1f451ed0bcad909d203ece06e1040a@nleyten.com>
	<20150217155011.GA5124@localhost.localdomain>
Message-ID: <8e6661f5abc99f6b93787a1e6f34e965@nleyten.com>
User-Agent: Roundcube Webmail/0.9.5
Cc: bitcoin-development@lists.sourceforge.net
Subject: Re: [Bitcoin-development] More precise type information in API
 reference
Precedence: list

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