doc: schemas for everything else.

Signed-off-by: Rusty Russell <[email protected]> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
gb000 · Jun 25, 2021 · 2ddecdc · 2ddecdc
1 parent 977cb62
commit 2ddecdc
Show file tree

Hide file tree

Showing 118 changed files with 3,038 additions and 429 deletions.
diff --git a/doc/lightning-dev-sendcustommsg.7 b/doc/lightning-dev-sendcustommsg.7
diff --git a/doc/lightning-dev-sendcustommsg.7.md b/doc/lightning-dev-sendcustommsg.7.md
@@ -47,6 +47,11 @@ as the message is queued.
 If any of the above limitations is not respected the method returns an
 explicit error message stating the issue.
 
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **status** (string): Information about where message was queued
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
 AUTHOR
 ------
 
@@ -62,3 +67,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:28ff2cdde9b35e81ceec3b1860facb1b2f91c5049ce33776b3c992621aba475d)
diff --git a/doc/lightning-fundpsbt.7 b/doc/lightning-fundpsbt.7
diff --git a/doc/lightning-fundpsbt.7.md b/doc/lightning-fundpsbt.7.md
@@ -71,16 +71,20 @@ if *excess_msat* was greater or equal to 31 + 546.
 RETURN VALUE
 ------------
 
-On success, returns the *psbt* containing the inputs, *feerate_per_kw*
-showing the exact numeric feerate it used, *estimated_final_weight* for
-the estimated weight of the transaction once fully signed, and
-*excess_msat* containing the amount above *satoshi* which is
-available.  This could be zero, or dust.  If *satoshi* was "all",
-then *excess_msat* is the entire amount once fees are subtracted
-for the weights of the inputs and startweight.
-
-If *reserve* was *true* or a non-zero number, then a *reservations*
-array is returned, exactly like *reserveinputs*.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **psbt** (string): Unsigned PSBT which fulfills the parameters given
+- **feerate_per_kw** (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight
+- **estimated_final_weight** (u32): The estimated weight of the transaction once fully signed
+- **excess_msat** (msat): The amount above *satoshi* which is available.  This could be zero, or dust; it will be zero if *change_outnum* is also returned
+- **change_outnum** (u32, optional): The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds)
+- **reservations** (array of objects, optional): If *reserve* was true or a non-zero number, just as per lightning-reserveinputs(7):
+  - **txid** (txid): The txid of the transaction
+  - **vout** (u32): The 0-based output number
+  - **was_reserved** (boolean): Whether this output was previously reserved (always *false*)
+  - **reserved** (boolean): Whether this output is now reserved (always *true*)
+  - **reserved_to_block** (u32): The blockheight the reservation will expire
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 If *excess_as_change* is true and the excess is enough to cover
 an additional output above the `dust_limit`, then an output is
@@ -110,4 +114,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:25b32367f5bbf6f1e53036c38b7b7d19eebf62fa749a3ab580e4093eedc88584)
+[comment]: # ( SHA256STAMP:4b3ea2f97eb94e65c752f165a989d99afee0eb8453178bf6a23e4a662fb6abf3)
diff --git a/doc/lightning-keysend.7 b/doc/lightning-keysend.7
diff --git a/doc/lightning-keysend.7.md b/doc/lightning-keysend.7.md
@@ -65,7 +65,20 @@ exceed *maxdelay*.
 RETURN VALUE
 ------------
 
-On success, `keysend` will return a number of internal statistics and details of the attempts to reach the *destination*.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **created_at** (number): the UNIX timestamp showing when this payment was initiated
+- **parts** (u32): how many attempts this took
+- **amount_msat** (msat): Amount the recipient received
+- **amount_sent_msat** (msat): Total amount we sent (including fees)
+- **status** (string): status of payment (always "complete")
+- **destination** (pubkey, optional): the final destination of the payment
+
+The following warnings may also be returned:
+- **warning_partial_completion**: Not all parts of a multi-part payment have completed
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 You can monitor the progress and retries of a payment using the lightning-paystatus(7) command.
 
@@ -100,3 +113,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:787ea6ae933da77756aca49aee68ba996cd54aea53b85ce2e5fcc85841022241)
diff --git a/doc/lightning-listsendpays.7 b/doc/lightning-listsendpays.7
diff --git a/doc/lightning-listsendpays.7.md b/doc/lightning-listsendpays.7.md
@@ -20,39 +20,27 @@ command per *pay*, so this command should be used with caution.
 RETURN VALUE
 ------------
 
-On success, an array of objects is returned, ordered by increasing *id*. 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).
-
- *bolt12*
-if **experimental-offers** is enabled, and `pay` was a given a bolt12
-invoice, this field will appear instead of *bolt11*.
+Note that the returned array is ordered by increasing *id*.
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object containing **payments** is returned.  It is an array of objects, where each object contains:
+- **id** (u64): unique ID for this payment attempt
+- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
+- **status** (string): status of the payment (one of "pending", "failed", "complete")
+- **created_at** (u64): the UNIX timestamp showing when this payment was initiated
+- **amount_sent_msat** (msat): The amount sent
+- **amount_msat** (msat, optional): The amount delivered to destination (if known)
+- **destination** (pubkey, optional): the final destination of the payment if known
+- **label** (string, optional): the label, if given to sendpay
+- **bolt11** (string, optional): the bolt11 string (if pay supplied one)
+- **bolt12** (string, optional): the bolt12 string (if supplied for pay: **experimental-offers** only).
+
+If **status** is "complete":
+  - **payment_preimage** (hex): the proof of payment: SHA256 of this **payment_hash** (always 64 characters)
+
+If **status** is "failed":
+  - **erroronion** (hex, optional): the onion message returned
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 AUTHOR
 ------
@@ -70,3 +58,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:db8e97cc84246f4e836ac7b2f39e265deb51cb0adacfcca8e05bb7cb9c3480de)