From 3cf91b23b9f59fcdd3b3468a91ea44931dd1e738 Mon Sep 17 00:00:00 2001 From: Vasil Dimov Date: Tue, 7 Jan 2020 17:59:24 +0100 Subject: [PATCH] doc: unify man pages error sections Change all man pages to follow the style of doc/lightning-pay.7.md for the section on returning errors. Changelog-None --- doc/lightning-disconnect.7 | 25 ++++++------------------- doc/lightning-disconnect.7.md | 14 ++++---------- doc/lightning-listchannels.7 | 24 ++++++++---------------- doc/lightning-listchannels.7.md | 12 +++--------- doc/lightning-listpeers.7 | 22 ++++------------------ doc/lightning-listpeers.7.md | 12 +++--------- 6 files changed, 28 insertions(+), 81 deletions(-) diff --git a/doc/lightning-disconnect.7 b/doc/lightning-disconnect.7 index 0427adb68..db60c6454 100644 --- a/doc/lightning-disconnect.7 +++ b/doc/lightning-disconnect.7 @@ -40,30 +40,17 @@ connection\. On success, an empty object is returned\. -.SH ERRORS -If \fIid\fR is invalid, an error message will be returned: +On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, +with \fBcode\fR being one of the following: -.nf .RS -{ "code" : -1, "message" : "Peer not connected" } - +.IP \[bu] +-32602: If the given parameters are wrong\. +.IP \[bu] +-1: Catchall nonspecific error\. .RE - -.fi - -If the peer has an active channel and \fIforce\fR is not set, an error -message will be returned: - -.nf -.RS -{ "code" : -1, "message" : "Peer is in state CHANNELD_NORMAL" } - - -.RE - -.fi .SH AUTHOR Michael Hawkins \fI\. diff --git a/doc/lightning-disconnect.7.md b/doc/lightning-disconnect.7.md index 05754f337..c0352a242 100644 --- a/doc/lightning-disconnect.7.md +++ b/doc/lightning-disconnect.7.md @@ -35,17 +35,11 @@ RETURN VALUE On success, an empty object is returned. -ERRORS ------- - -If *id* is invalid, an error message will be returned: - - { "code" : -1, "message" : "Peer not connected" } - -If the peer has an active channel and *force* is not set, an error -message will be returned: +On error the returned object will contain `code` and `message` properties, +with `code` being one of the following: - { "code" : -1, "message" : "Peer is in state CHANNELD_NORMAL" } +- -32602: If the given parameters are wrong. +- -1: Catchall nonspecific error. AUTHOR ------ diff --git a/doc/lightning-listchannels.7 b/doc/lightning-listchannels.7 index 169470907..012f06733 100644 --- a/doc/lightning-listchannels.7 +++ b/doc/lightning-listchannels.7 @@ -32,6 +32,7 @@ list of 0 or more objects\. Each object in the list contains the following data: +.RS .IP \[bu] \fIsource\fR : The node providing entry to the channel, specifying the fees charged for using the channel in that direction\. @@ -79,27 +80,20 @@ through this channel\. \fIhtlc_maximum_msat\fR : The maximum payment which can be send through this channel\. +.RE If \fIshort_channel_id\fR or \fIsource\fR is supplied and no matching channels are found, a "channels" object with an empty list is returned\. -.SH ERRORS -If \fIshort_channel_id\fR is not a valid short_channel_id, an error -message will be returned: +On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, +with \fBcode\fR being one of the following: -.nf .RS -{ "code" : -32602, - "message" : "'short_channel_id' should be a short channel id, not '...'" } - +.IP \[bu] +-32602: If the given parameters are wrong\. .RE - -.fi - -Similarly if \fIsource\fR is not a valid pubkey\. - .SH AUTHOR Michael Hawkins \fI\. @@ -115,6 +109,7 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Lightning RFC site +.RS .IP \[bu] BOLT #2: @@ -128,7 +123,4 @@ BOLT #7: -.HL - -Last updated 2019-06-12 11:16:20 CEST - +.RE diff --git a/doc/lightning-listchannels.7.md b/doc/lightning-listchannels.7.md index 296c6e200..181ee91d4 100644 --- a/doc/lightning-listchannels.7.md +++ b/doc/lightning-listchannels.7.md @@ -65,16 +65,10 @@ through this channel. If *short\_channel\_id* or *source* is supplied and no matching channels are found, a "channels" object with an empty list is returned. -ERRORS ------- - -If *short\_channel\_id* is not a valid short\_channel\_id, an error -message will be returned: - - { "code" : -32602, - "message" : "'short_channel_id' should be a short channel id, not '...'" } +On error the returned object will contain `code` and `message` properties, +with `code` being one of the following: -Similarly if *source* is not a valid pubkey. +- -32602: If the given parameters are wrong. AUTHOR ------ diff --git a/doc/lightning-listpeers.7 b/doc/lightning-listpeers.7 index ae747f550..70305ffd5 100644 --- a/doc/lightning-listpeers.7 +++ b/doc/lightning-listpeers.7 @@ -67,29 +67,15 @@ peer at the specified \fIlevel\fR If \fIid\fR is supplied and no matching nodes are found, a "peers" object with an empty list is returned\. -.SH ERRORS -If \fIid\fR is not a valid public key, an error message will be returned: +On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, +with \fBcode\fR being one of the following: -.nf .RS -{ "code" : -32602, "message" : "'id' should be a pubkey, not '...'" } - - -.RE - -.fi - -If \fIlevel\fR is not a valid log level, an error message will be returned: - -.nf -.RS -{ "code" : -32602, "message" : "'level' should be 'io', 'debug', 'info', or 'unusual', not '...'" } - +.IP \[bu] +-32602: If the given parameters are wrong\. .RE - -.fi .SH AUTHOR Michael Hawkins \fI\. diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md index 762996a65..54d083a02 100644 --- a/doc/lightning-listpeers.7.md +++ b/doc/lightning-listpeers.7.md @@ -53,16 +53,10 @@ peer at the specified *level* If *id* is supplied and no matching nodes are found, a "peers" object with an empty list is returned. -ERRORS ------- - -If *id* is not a valid public key, an error message will be returned: - - { "code" : -32602, "message" : "'id' should be a pubkey, not '...'" } - -If *level* is not a valid log level, an error message will be returned: +On error the returned object will contain `code` and `message` properties, +with `code` being one of the following: - { "code" : -32602, "message" : "'level' should be 'io', 'debug', 'info', or 'unusual', not '...'" } +- -32602: If the given parameters are wrong. AUTHOR ------