pay: update documentation.

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

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - JSON API: `invoice` expiry defaults to 7 days, and can have s/m/h/d/w suffixes.
 - Config: Increased default amount for minimal channel capacity from 1k sat to 10k sat.
 - Build: Non-developer builds are now done with "-Og" optimization.
+- JSON API: `pay` will no longer return failure until it is no longer retrying; previously it could "timeout" but still make the payment.
 
 ### Deprecated
 

doc/lightning-pay.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-pay
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 02/23/2019
+.\"      Date: 05/22/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-PAY" "7" "02/23/2019" "\ \&" "\ \&"
+.TH "LIGHTNING\-PAY" "7" "05/22/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -40,7 +40,7 @@ The \fIlabel\fR field is used to attach a label to payments, and is returned in
 .sp
 The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&.
 .sp
-The command will keep finding routes and retrying the payment until it succeeds, or the given \fIretry_for\fR seconds passes\&. Note that the command may stop retrying while a pending payment is ongoing, which you need to monitor with \fBlistpays\fR\&. \fIretry_for\fR defaults to 60 seconds and can only be an integer\&.
+Until \fIretry_for\fR seconds passes (default: 60), the command will keep finding routes and retrying the payment\&. However, a payment may be delayed for up to maxdelay blocks by another node; clients should be prepared for this worst case\&.
 .sp
 When using \fIlightning\-cli\fR, you may skip optional parameters by using \fInull\fR\&. Alternatively, use \fB\-k\fR option to provide parameters by name\&.
 .SH "RANDOMIZATION"
@@ -78,7 +78,7 @@ Both randomizations respect \fImaxfeepercent\fR\&. Route randomization plus the
 .sp
 On success, this returns the payment \fIpreimage\fR which hashes to the \fIpayment_hash\fR to prove that the payment was successful\&. It will also return, a \fIgetroute_tries\fR and a \fIsendpay_tries\fR statistics for the number of times it internally called \fBgetroute\fR and \fBsendpay\fR\&.
 .sp
-On error, if the error occurred from a node other than the final destination, the route table will be updated so that getroute(7) should return an alternate route (if any)\&. An error from the final destination implies the payment should not be retried\&.
+You can monitor the progress and retries of a payment using the lightning\-paystatus(7) command\&.
 .sp
 The following error codes may occur:
 .sp
@@ -101,19 +101,6 @@ The following error codes may occur:
 .sp -1
 .IP \(bu 2.3
 .\}
-200\&. Payment timed out while a payment is in progress\&. Monitor the status of that payment with
-\fIlistpays\fR
-command\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
 201\&. Already paid with this
 \fIhash\fR
 using different amount or destination\&.

doc/lightning-pay.7.txt

@@ -37,11 +37,10 @@ The response will occur when the payment fails or succeeds.  Once a
 payment has succeeded, calls to *pay* with the same 'bolt11' will
 succeed immediately.
 
-The command will keep finding routes and retrying the payment until
-it succeeds, or the given 'retry_for' seconds passes.
-Note that the command may stop retrying while a pending payment is
-ongoing, which you need to monitor with *listpays*.
-'retry_for' defaults to 60 seconds and can only be an integer.
+Until 'retry_for' seconds passes (default: 60), the command will keep
+finding routes and retrying the payment.  However, a payment may be
+delayed for up to `maxdelay` blocks by another node; clients should be
+prepared for this worst case.
 
 When using 'lightning-cli', you may skip optional parameters by using
 'null'.
@@ -82,16 +81,12 @@ It will also return, a 'getroute_tries' and a 'sendpay_tries'
 statistics for the number of times it internally called *getroute*
 and *sendpay*.
 
-On error, if the error occurred from a node other than the final
-destination, the route table will be updated so that getroute(7)
-should return an alternate route (if any).  An error from the final
-destination implies the payment should not be retried.
+You can monitor the progress and retries of a payment using the
+lightning-paystatus(7) command.
 
 The following error codes may occur:
 
 * -1. Catchall nonspecific error.
-* 200. Payment timed out while a payment is in progress. Monitor
-  the status of that payment with 'listpays' command.
 * 201. Already paid with this 'hash' using different amount or
   destination.
 * 203. Permanent failure at destination. The 'data' field of