public inbox for bitcoindev@googlegroups.com
 help / color / mirror / Atom feed

From: Dario Teixeira <dario.teixeira@nleyten•com>
To: "David A. Harding" <dave@dtrt•org>
Cc: bitcoin-development@lists•sourceforge.net
Subject: Re: [Bitcoin-development] More precise type information in API reference
Date: Tue, 17 Feb 2015 18:46:17 +0000	[thread overview]
Message-ID: <8e6661f5abc99f6b93787a1e6f34e965@nleyten.com> (raw)
In-Reply-To: <20150217155011.GA5124@localhost.localdomain>

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

     prev parent reply	other threads:[~2015-02-17 18:46 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-02-17 13:00 Dario Teixeira
2015-02-17 13:33 ` Dario Teixeira
2015-02-17 15:50   ` David A. Harding
2015-02-17 18:46     ` Dario Teixeira [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8e6661f5abc99f6b93787a1e6f34e965@nleyten.com \
    --to=dario.teixeira@nleyten$(echo .)com \
    --cc=bitcoin-development@lists$(echo .)sourceforge.net \
    --cc=dave@dtrt$(echo .)org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox