Start all command descriptions with a verb ("Show", "Set", etc.). Remove unused help texts.

lightningd/chaintopology.c

@@ -594,8 +594,7 @@ static void json_dev_blockheight(struct command *cmd,
 static const struct json_command dev_blockheight = {
 	"dev-blockheight",
 	json_dev_blockheight,
-	"Find out what block height we have",
+	"Show current block height"
-	"Returns { blockheight: u32 } on success"
 };
 AUTODATA(json_command, &dev_blockheight);
 
@@ -656,8 +655,7 @@ static void json_dev_setfees(struct command *cmd,
 static const struct json_command dev_setfees_command = {
 	"dev-setfees",
 	json_dev_setfees,
-	"Set feerate in satoshi-per-kw for {immediate}, {normal} and {slow} (each optional).  Returns the value of those three feerates.",
+	"Set feerate in satoshi-per-kw for {immediate}, {normal} and {slow} (each optional) and show the value of those three feerates"
-	"Allows testing of feerate changes"
 };
 AUTODATA(json_command, &dev_setfees_command);
 

lightningd/dev_ping.c

@@ -102,7 +102,6 @@ static void json_dev_ping(struct command *cmd,
 static const struct json_command dev_ping_command = {
 	"dev-ping",
 	json_dev_ping,
-	"Offer {id} a ping of length {len} asking for {pongbytes}",
+	"Send {peerid} a ping of length {len} asking for {pongbytes}"
-	"Returns { totlen: u32 } on success"
 };
 AUTODATA(json_command, &dev_ping_command);

lightningd/gossip_control.c

@@ -251,9 +251,10 @@ static void json_listnodes(struct command *cmd, const char *buffer,
 }
 
 static const struct json_command listnodes_command = {
-    "listnodes", json_listnodes,
+	"listnodes",
-    "List a nodes in our local network view (or all, if no {id})",
+	json_listnodes,
-    "Returns a list of all nodes that we know about"};
+	"Show all nodes in our local network view"
+};
 AUTODATA(json_command, &listnodes_command);
 
 static void json_getroute_reply(struct subd *gossip, const u8 *reply, const int *fds,
@@ -335,9 +336,9 @@ static void json_getroute(struct command *cmd, const char *buffer, const jsmntok
 }
 
 static const struct json_command getroute_command = {
-	"getroute", json_getroute,
+	"getroute",
-	"Return route to {id} for {msatoshi}, using {riskfactor} and optional {cltv} (default 9)",
+	json_getroute,
-	"Returns a {route} array of {id} {msatoshi} {delay}: msatoshi and delay (in blocks) is cumulative."
+	"Show route to {id} for {msatoshi}, using {riskfactor} and optional {cltv} (default 9)"
 };
 AUTODATA(json_command, &getroute_command);
 
@@ -412,6 +413,8 @@ static void json_listchannels(struct command *cmd, const char *buffer,
 }
 
 static const struct json_command listchannels_command = {
-    "listchannels", json_listchannels, "List all known channels.",
+	"listchannels",
-    "Returns a 'channels' array with all known channels including their fees."};
+	json_listchannels,
+	"Show all known channels"
+};
 AUTODATA(json_command, &listchannels_command);

lightningd/invoice.c

@@ -197,8 +197,7 @@ static void json_invoice(struct command *cmd,
 static const struct json_command invoice_command = {
 	"invoice",
 	json_invoice,
-	"Create invoice for {msatoshi} with {label} and {description} with optional {expiry} seconds (default 1 hour)",
+	"Create an invoice for {msatoshi} with {label} and {description} with optional {expiry} seconds (default 1 hour)"
-	"Returns the {payment_hash}, {expires_at} and {bolt11} on success, and {description} if too large for {bolt11}. "
 };
 AUTODATA(json_command, &invoice_command);
 
@@ -259,7 +258,6 @@ static const struct json_command listinvoice_command = {
 	"listinvoice",
 	json_listinvoice,
 	"(DEPRECATED) Show invoice {label} (or all, if no {label}))",
-	"Returns an array of {label}, {payment_hash}, {msatoshi} (if set), {complete}, {pay_index} (if paid) and {expires_time} on success. ",
 	.deprecated = true
 };
 AUTODATA(json_command, &listinvoice_command);
@@ -273,8 +271,7 @@ static void json_listinvoices(struct command *cmd,
 static const struct json_command listinvoices_command = {
 	"listinvoices",
 	json_listinvoices,
-	"Show invoice {label} (or all, if no {label}))",
+	"Show invoice {label} (or all, if no {label})"
-	"Returns an array of {label}, {payment_hash}, {msatoshi} (if set), {status}, {pay_index} (if paid) and {expires_at} on success. ",
 };
 AUTODATA(json_command, &listinvoices_command);
 
@@ -333,7 +330,6 @@ static const struct json_command delinvoice_command = {
 	"delinvoice",
 	json_delinvoice,
 	"Delete unpaid invoice {label} with {status}",
-	"Returns {label}, {payment_hash}, {msatoshi} (if set), {status}, {pay_index} (if paid) and {expires_at} on success. "
 };
 AUTODATA(json_command, &delinvoice_command);
 
@@ -375,8 +371,7 @@ static void json_waitanyinvoice(struct command *cmd,
 static const struct json_command waitanyinvoice_command = {
 	"waitanyinvoice",
 	json_waitanyinvoice,
-	"Wait for the next invoice to be paid, after {lastpay_index} (if supplied)))",
+	"Wait for the next invoice to be paid, after {lastpay_index} (if supplied)"
-	"Returns {label}, {payment_hash}, {msatoshi} (if set), {status}, {pay_index} and {expires_at} on success. "
 };
 AUTODATA(json_command, &waitanyinvoice_command);
 
@@ -420,8 +415,7 @@ static void json_waitinvoice(struct command *cmd,
 static const struct json_command waitinvoice_command = {
 	"waitinvoice",
 	json_waitinvoice,
-	"Wait for an incoming payment matching the invoice with {label}",
+	"Wait for an incoming payment matching the invoice with {label}"
-	"Returns {label}, {payment_hash}, {msatoshi} (if set), {complete}, {pay_index} and {expires_at} on success"
 };
 AUTODATA(json_command, &waitinvoice_command);
 
@@ -574,7 +568,6 @@ static void json_decodepay(struct command *cmd,
 static const struct json_command decodepay_command = {
 	"decodepay",
 	json_decodepay,
-	"Parse and decode {bolt11} if possible, using {description} if necessary",
+	"Decode {bolt11}, using {description} if necessary"
-	"Returns a verbose description on success"
 };
 AUTODATA(json_command, &decodepay_command);

lightningd/jsonrpc.c

@@ -52,8 +52,7 @@ static void json_help(struct command *cmd,
 static const struct json_command help_command = {
 	"help",
 	json_help,
-	"List available commands",
+	"Show available commands"
-	"Returns an array {help} of available commands",
 };
 AUTODATA(json_command, &help_command);
 
@@ -71,8 +70,7 @@ static void json_stop(struct command *cmd,
 static const struct json_command stop_command = {
 	"stop",
 	json_stop,
-	"Shutdown the lightningd process",
+	"Shut down the lightningd process"
-	"What part of shutdown wasn't clear?"
 };
 AUTODATA(json_command, &stop_command);
 
@@ -190,8 +188,7 @@ static void json_getlog(struct command *cmd,
 static const struct json_command getlog_command = {
 	"getlog",
 	json_getlog,
-	"Get logs, with optional level: [io|debug|info|unusual]",
+	"Show logs, with optional log {level} (info|unusual|debug|io)"
-	"Returns log array"
 };
 AUTODATA(json_command, &getlog_command);
 
@@ -230,8 +227,7 @@ static void json_rhash(struct command *cmd,
 static const struct json_command dev_rhash_command = {
 	"dev-rhash",
 	json_rhash,
-	"SHA256 of {secret}",
+	"Show SHA256 of {secret}"
-	"Returns a hash value"
 };
 AUTODATA(json_command, &dev_rhash_command);
 
@@ -244,8 +240,7 @@ static void json_crash(struct command *cmd,
 static const struct json_command dev_crash_command = {
 	"dev-crash",
 	json_crash,
-	"Call fatal()",
+	"Crash lightningd by calling fatal()"
-	"Simple crash test for developers"
 };
 AUTODATA(json_command, &dev_crash_command);
 #endif /* DEVELOPER */
@@ -274,8 +269,7 @@ static void json_getinfo(struct command *cmd,
 static const struct json_command getinfo_command = {
 	"getinfo",
 	json_getinfo,
-	"Get general information about this node",
+	"Show information about this node"
-	"Returns {id}, {port}, {testnet}, etc."
 };
 AUTODATA(json_command, &getinfo_command);
 

lightningd/jsonrpc.h

@@ -52,7 +52,6 @@ struct json_command {
 	void (*dispatch)(struct command *,
 			 const char *buffer, const jsmntok_t *params);
 	const char *description;
-	const char *help;
 	bool deprecated;
 };
 

lightningd/memdump.c

@@ -62,8 +62,7 @@ static void json_memdump(struct command *cmd,
 static const struct json_command dev_memdump_command = {
 	"dev-memdump",
 	json_memdump,
-	"Dump the memory objects currently used",
+	"Show memory objects currently in use"
-	"Debugging tool for memory leaks"
 };
 AUTODATA(json_command, &dev_memdump_command);
 
@@ -160,8 +159,7 @@ static void json_memleak(struct command *cmd,
 static const struct json_command dev_memleak_command = {
 	"dev-memleak",
 	json_memleak,
-	"Dump the memory objects unreferenced",
+	"Show unreferenced memory objects"
-	"Debugging tool for memory leaks"
 };
 AUTODATA(json_command, &dev_memleak_command);
 #endif /* DEVELOPER */

lightningd/pay.c

@@ -328,8 +328,7 @@ static void json_sendpay(struct command *cmd,
 static const struct json_command sendpay_command = {
 	"sendpay",
 	json_sendpay,
-	"Send along {route} in return for preimage of {rhash}",
+	"Send along {route} in return for preimage of {rhash}"
-	"Returns the {preimage} on success"
 };
 AUTODATA(json_command, &sendpay_command);
 
@@ -432,8 +431,7 @@ static void json_pay(struct command *cmd,
 static const struct json_command pay_command = {
 	"pay",
 	json_pay,
-	"Send payment specified by {bolt11} with optional {msatoshi} (iff {bolt11} does not have amount), {description} (required if {bolt11} uses description hash) and {riskfactor} (default 1.0)",
+	"Send payment specified by {bolt11} with optional {msatoshi} (if and only if {bolt11} does not have amount), {description} (required if {bolt11} uses description hash) and {riskfactor} (default 1.0)"
-	"Returns the {preimage} on success"
 };
 AUTODATA(json_command, &pay_command);
 
@@ -525,7 +523,6 @@ static void json_listpayments(struct command *cmd, const char *buffer,
 static const struct json_command listpayments_command = {
 	"listpayments",
 	json_listpayments,
-	"Get a list of outgoing payments",
+	"Show outgoing payments"
-	"Returns a list of payments with {payment_hash}, {destination}, {msatoshi}, {created_at} and {status} (and {payment_preimage} if {status} is 'complete')"
 };
 AUTODATA(json_command, &listpayments_command);

lightningd/peer_control.c

@@ -761,8 +761,7 @@ static void json_connect(struct command *cmd,
 static const struct json_command connect_command = {
 	"connect",
 	json_connect,
-	"Connect to {id} at {host} (which can end in ':port' if not default)",
+	"Connect to {id} at {host} (which can end in ':port' if not default)"
-	"Returns the {id} on success (once channel established)"
 };
 AUTODATA(json_command, &connect_command);
 
@@ -954,8 +953,7 @@ static void json_listpeers(struct command *cmd,
 static const struct json_command listpeers_command = {
 	"listpeers",
 	json_listpeers,
-	"List the current peers, if {level} is set, include {log}s",
+	"Show current peers, if {level} is set, include {log}s"
-	"Returns a 'peers' array"
 };
 AUTODATA(json_command, &listpeers_command);
 
@@ -2661,8 +2659,7 @@ static void json_fund_channel(struct command *cmd,
 static const struct json_command fund_channel_command = {
 	"fundchannel",
 	json_fund_channel,
-	"Fund channel with {id} using {satoshi} satoshis",
+	"Fund channel with {id} using {satoshi} satoshis"
-	"Returns {tx} once channel established"
 };
 AUTODATA(json_command, &fund_channel_command);
 
@@ -2727,8 +2724,7 @@ static void json_close(struct command *cmd,
 static const struct json_command close_command = {
 	"close",
 	json_close,
-	"Close the channel with peer {id}",
+	"Close the channel with peer {id}"
-	"Returns an empty result on success"
 };
 AUTODATA(json_command, &close_command);
 
@@ -2822,9 +2818,7 @@ static void json_sign_last_tx(struct command *cmd,
 static const struct json_command dev_sign_last_tx = {
 	"dev-sign-last-tx",
 	json_sign_last_tx,
-	"Sign and return the last commitment transaction with peer {id}",
+	"Sign and show the last commitment transaction with peer {id}"
-	"Sign last transaction with peer @id, return as @tx."
-	"  This should never be called outside testing!"
 };
 AUTODATA(json_command, &dev_sign_last_tx);
 
@@ -2854,8 +2848,7 @@ static void json_dev_fail(struct command *cmd,
 static const struct json_command dev_fail_command = {
 	"dev-fail",
 	json_dev_fail,
-	"Fail with peer {id}",
+	"Fail with peer {id}"
-	"Returns {} on success"
 };
 AUTODATA(json_command, &dev_fail_command);
 
@@ -2906,8 +2899,7 @@ static void json_dev_reenable_commit(struct command *cmd,
 static const struct json_command dev_reenable_commit = {
 	"dev-reenable-commit",
 	json_dev_reenable_commit,
-	"Reenable the commit timer on peer {id}",
+	"Re-enable the commit timer on peer {id}"
-	"Returns {} on success"
 };
 AUTODATA(json_command, &dev_reenable_commit);
 #endif /* DEVELOPER */

wallet/walletrpc.c

@@ -306,8 +306,7 @@ static void json_withdraw(struct command *cmd,
 static const struct json_command withdraw_command = {
 	"withdraw",
 	json_withdraw,
-	"Send to {destination} address {satoshi} (or 'all') amount via Bitcoin transaction",
+	"Send to {destination} address {satoshi} (or 'all') amount via Bitcoin transaction"
-	"Returns the withdrawal transaction ID"
 };
 AUTODATA(json_command, &withdraw_command);
 
@@ -357,8 +356,7 @@ static void json_newaddr(struct command *cmd,
 static const struct json_command newaddr_command = {
 	"newaddr",
 	json_newaddr,
-	"Get a new address to fund a channel",
+	"Get a new address to fund a channel"
-	"Returns {address} a p2sh address"
 };
 AUTODATA(json_command, &newaddr_command);
 
@@ -383,7 +381,8 @@ static void json_listfunds(struct command *cmd, const char *buffer,
 }
 
 static const struct json_command listfunds_command = {
-    "listfunds", json_listfunds,
+	"listfunds",
-    "List funds available to the daemon to open channels",
+	json_listfunds,
-    "Returns an array of available outputs"};
+	"Show funds available for opening channels"
+};
 AUTODATA(json_command, &listfunds_command);