From fef1649ca409d325f86abc182816ee2aa0f9da31 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 11 Nov 2024 10:48:03 +1030 Subject: [PATCH] doc: improve documentation of listpays 1. It's called listpays not listpay. 2. "index" does NOT have a default value (it must be specified if limit or start are used) 3. Note that limit and start have effects on accuracy, since we combine records. Signed-off-by: Rusty Russell --- cln-rpc/src/model.rs | 2 +- contrib/msggen/msggen/schema.json | 14 ++++++++------ doc/schemas/lightning-listpays.json | 14 ++++++++------ 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/cln-rpc/src/model.rs b/cln-rpc/src/model.rs index 1b3f6c747b9a..bee31ee8d7df 100644 --- a/cln-rpc/src/model.rs +++ b/cln-rpc/src/model.rs @@ -2615,7 +2615,7 @@ pub mod requests { "listoffers" } } - /// ['If neither *in_channel* nor *out_channel* is specified, it controls ordering.'] + /// ['If neither *in_channel* nor *out_channel* is specified, it controls ordering, by `created` or `updated`.'] #[derive(Copy, Clone, Debug, Deserialize, Serialize, PartialEq, Eq)] pub enum ListpaysIndex { #[serde(rename = "created")] diff --git a/contrib/msggen/msggen/schema.json b/contrib/msggen/msggen/schema.json index 535dc03471f0..db26681a3215 100644 --- a/contrib/msggen/msggen/schema.json +++ b/contrib/msggen/msggen/schema.json @@ -22971,7 +22971,7 @@ "rpc": "listpays", "title": "Command for querying payment status", "description": [ - "The **listpay** RPC command gets the status of all *pay* commands, or a single one if either *bolt11* or *payment_hash* was specified." + "The **listpays** RPC command gets the status of all *pay* commands (by combining results from listsendpays which lists every payment part), or a single one if either *bolt11* or *payment_hash* was specified." ], "categories": [ "readonly" @@ -23011,22 +23011,24 @@ "updated" ], "description": [ - "If neither *in_channel* nor *out_channel* is specified, it controls ordering." - ], - "default": "`created`" + "If neither *in_channel* nor *out_channel* is specified, it controls ordering, by `created` or `updated`." + ] }, "start": { "type": "u64", "added": "v24.11", "description": [ - "If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)." + "If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7).", + "NOTE: if this is used, `amount_sent_msat` and `number_of_parts` fields may be lower than expected, as not all payment parts will be considered" ] }, "limit": { "type": "u32", "added": "v24.11", "description": [ - "If `index` is specified, `limit` can be used to specify the maximum number of entries to return." + "If `index` is specified, `limit` can be used to specify the maximum number of entries to return.", + "NOTE: if this is used, `amount_sent_msat` and `number_of_parts` fields may be lower than expected, as not all payment parts will be considered", + "NOTE: the actual number returned may be less than the limit, as individual payment parts are combined together" ] } } diff --git a/doc/schemas/lightning-listpays.json b/doc/schemas/lightning-listpays.json index 49e6c2a3bcc7..589699db137b 100644 --- a/doc/schemas/lightning-listpays.json +++ b/doc/schemas/lightning-listpays.json @@ -4,7 +4,7 @@ "rpc": "listpays", "title": "Command for querying payment status", "description": [ - "The **listpay** RPC command gets the status of all *pay* commands, or a single one if either *bolt11* or *payment_hash* was specified." + "The **listpays** RPC command gets the status of all *pay* commands (by combining results from listsendpays which lists every payment part), or a single one if either *bolt11* or *payment_hash* was specified." ], "categories": [ "readonly" @@ -44,22 +44,24 @@ "updated" ], "description": [ - "If neither *in_channel* nor *out_channel* is specified, it controls ordering." - ], - "default": "`created`" + "If neither *in_channel* nor *out_channel* is specified, it controls ordering, by `created` or `updated`." + ] }, "start": { "type": "u64", "added": "v24.11", "description": [ - "If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)." + "If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7).", + "NOTE: if this is used, `amount_sent_msat` and `number_of_parts` fields may be lower than expected, as not all payment parts will be considered" ] }, "limit": { "type": "u32", "added": "v24.11", "description": [ - "If `index` is specified, `limit` can be used to specify the maximum number of entries to return." + "If `index` is specified, `limit` can be used to specify the maximum number of entries to return.", + "NOTE: if this is used, `amount_sent_msat` and `number_of_parts` fields may be lower than expected, as not all payment parts will be considered", + "NOTE: the actual number returned may be less than the limit, as individual payment parts are combined together" ] } }