doc: update listpayments man page to match current semantics.

It didn't show the optional parameters, and the output fields were
obsolete.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/lightning-listpayments.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-listpayments
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 04/26/2018
+.\"      Date: 02/22/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-LISTPAYME" "7" "04/26/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-LISTPAYME" "7" "02/22/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -28,22 +28,84 @@
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
 .SH "NAME"
-lightning-listpayments \- Command for querying payment status
+lightning-listpayments \- Low\-level command for querying payment status
 .SH "SYNOPSIS"
 .sp
-\fBlistpayments\fR
+\fBlistpayments\fR [\fIbolt11\fR] [\fIpayment_hash\fR]
 .SH "DESCRIPTION"
 .sp
-The \fBlistpayments\fR RPC command gets the status of all \fIpay\fR and \fIsendpay\fR commands\&.
+The \fBlistpayments\fR RPC command gets the status of all \fIsendpay\fR commands (which is also used by the \fIpay\fR command), or with \fIbolt11\fR or \fIpayment_hash\fR limits results to that specific payment\&. You cannot specify both\&.
+.sp
+Note that in future there may be more than one concurrent \fIsendpay\fR command per \fIpay\fR, so this command should be used with caution\&.
 .SH "RETURN VALUE"
 .sp
-On success, an array of objects is returned\&. Each object contains an \fIid\fR (unique internal value assigned at creation), \fIpayment_hash\fR, \fIdestination\fR, \fImsatoshi\fR and \fItimestamp\fR (UNIX timestamp indicating when it was initiated), and a \fIstatus\fR which is one of \fIpending\fR (in progress), \fIcomplete\fR (successfully paid) or \fIfailed\fR\&.
+On success, an array of objects is returned\&. Each object contains:
+.PP
+\fIid\fR
+.RS 4
+unique internal value assigned at creation
+.RE
+.PP
+\fIpayment_hash\fR
+.RS 4
+the hash of the
+\fIpayment_preimage\fR
+which will prove payment\&.
+.RE
+.PP
+\fIdestination\fR
+.RS 4
+the final destination of the payment\&.
+.RE
+.PP
+\fIamount_msat\fR
+.RS 4
+the amount the destination received, in "NNNmsat" format\&.
+.RE
+.PP
+\fIcreated_at\fR
+.RS 4
+the UNIX timestamp showing when this payment was initiated\&.
+.RE
+.PP
+\fIstatus\fR
+.RS 4
+one of
+\fIcomplete\fR,
+\fIfailed\fR
+or
+\fIpending\fR\&.
+.RE
+.PP
+\fIpayment_preimage\fR
+.RS 4
+(if
+\fIstatus\fR
+is
+\fIcomplete\fR) proves payment was received\&.
+.RE
+.PP
+\fIlabel\fR
+.RS 4
+optional
+\fIlabel\fR, if provided to
+\fIsendpay\fR\&.
+.RE
+.PP
+\fIbolt11\fR
+.RS 4
+the
+\fIbolt11\fR
+argument given to
+\fIpay\fR
+(may be missing for pre\-0\&.7 payments)\&.
+.RE
 .SH "AUTHOR"
 .sp
 Christian Decker <decker\&.christian@gmail\&.com> is mainly responsible\&.
 .SH "SEE ALSO"
 .sp
-lightning\-pay(7), lightning\-sendpay(7), lightning\-listinvoice(7)\&.
+lightning\-listpays(7), lightning\-sendpay(7), lightning\-listinvoice(7)\&.
 .SH "RESOURCES"
 .sp
 Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-listpayments.7.txt

@@ -4,21 +4,36 @@ LIGHTNING-LISTPAYMENTS(7)
 
 NAME
 ----
-lightning-listpayments - Command for querying payment status
+lightning-listpayments - Low-level command for querying payment status
 
 SYNOPSIS
 --------
-*listpayments*
+*listpayments* ['bolt11'] ['payment_hash']
 
 DESCRIPTION
 -----------
 
-The *listpayments* RPC command gets the status of all 'pay' and
-'sendpay' commands.
+The *listpayments* RPC command gets the status of all 'sendpay'
+commands (which is also used by the 'pay' command), or with 'bolt11'
+or 'payment_hash' limits results to that specific payment.  You cannot
+specify both.
+
+Note that in future there may be more than one concurrent 'sendpay'
+command per 'pay', so this command should be used with caution.
 
 RETURN VALUE
 ------------
-On success, an array of objects is returned.  Each object contains an 'id' (unique internal value assigned at creation), 'payment_hash', 'destination', 'msatoshi' and 'timestamp' (UNIX timestamp indicating when it was initiated), and a 'status' which is one of 'pending' (in progress), 'complete' (successfully paid) or 'failed'.
+On success, an array of objects is returned.  Each object contains:
+
+'id':: unique internal value assigned at creation
+'payment_hash':: the hash of the 'payment_preimage' which will prove payment.
+'destination':: the final destination of the payment.
+'amount_msat':: the amount the destination received, in "NNNmsat" format.
+'created_at':: the UNIX timestamp showing when this payment was initiated.
+'status':: one of 'complete', 'failed' or 'pending'.
+'payment_preimage':: (if 'status' is 'complete') proves payment was received.
+'label':: optional 'label', if provided to 'sendpay'.
+'bolt11':: the 'bolt11' argument given to 'pay' (may be missing for pre-0.7 payments).
 
 //FIXME:Enumerate errors
 
@@ -28,7 +43,7 @@ Christian Decker <decker.christian@gmail.com> is mainly responsible.
 
 SEE ALSO
 --------
-lightning-pay(7), lightning-sendpay(7), lightning-listinvoice(7).
+lightning-listpays(7), lightning-sendpay(7), lightning-listinvoice(7).
 
 RESOURCES
 ---------