doc: Document the changes to the 'plugin' command

CHANGELOG.md

@@ -26,6 +26,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - JSON API: `fundchannel_cancel` is extended to work before funding broadcast.
 - JSON API: The parameter `exclude` of `getroute` now also support node-id.
 - JSON-API: `pay` can exclude error nodes if the failcode of `sendpay` has the NODE bit set
+- JSON API: The `plugin` command now returns on error. A timeout of 20 seconds is added to `start` and `startdir`
+            subcommands at the end of which the plugin is errored if it did not complete the handshake with `lightningd`.
+- JSON API: The `plugin` command does not allow to start static plugins after `lightningd` startup anymore.
 
 ### Deprecated
 

doc/lightning-plugin.7

@@ -14,16 +14,18 @@ optionally one or two parameters which describes the plugin on which the
 action has to be taken\.
 
 
-The \fIstart\fR command takes a path as parameter and will load the plugin
+The \fIstart\fR command takes a path as the first parameter and will load the
-available from this path\.
+plugin available from this path\. It will wait for the plugin to complete
+the handshake with \fBlightningd\fR for 20 seconds at the most\.
 
 
-The \fIstop\fR command takes a plugin name as parameter and will kill and
+The \fIstop\fR command takes a plugin name as parameter\. It will kill and
 unload the specified plugin\.
 
 
-The \fIstartdir\fR command takes a directory path as parameter and will load
+The \fIstartdir\fR command takes a directory path as first parameter and will
-all plugins this directory contains\.
+load all plugins this directory contains\. It will wait for each plugin to
+complete the handshake with \fBlightningd\fR for 20 seconds at the most\.
 
 
 The \fIrescan\fR command starts all not-already-loaded plugins from the
@@ -34,20 +36,21 @@ The \fIlist\fR command will return all the active plugins\.
 
 .SH RETURN VALUE
 
-On success, this returns an array \fIplugins\fR of objects, one by plugin\.
+On success, all subcommands but \fIstop\fR return an array \fIplugins\fR of
+objects, one by plugin\.
 Each object contains the name of the plugin (\fIname\fR field) and its
 status (\fIactive\fR boolean field)\. Since plugins are configured
 asynchronously, a freshly started plugin may not appear immediately\.
 
+
+On error, the reason why the action could not be taken upon the
+plugin is returned\.
+
 .SH AUTHOR
 
-Antoine Poinsot \fI<darosior@protonmail.com\fR> is mainly responsible\.
+Antoine Poinsot (\fIdarosior@protonmail.com\fR) is mainly responsible\.
 
 .SH RESOURCES
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-.HL
-
-Last updated 2019-07-29 12:57:57 CEST
-

doc/lightning-plugin.7.md

@@ -15,14 +15,16 @@ restart lightningd. It takes 1 to 3 parameters: a command
 optionally one or two parameters which describes the plugin on which the
 action has to be taken.
 
-The *start* command takes a path as parameter and will load the plugin
+The *start* command takes a path as the first parameter and will load the
-available from this path.
+plugin available from this path. It will wait for the plugin to complete
+the handshake with `lightningd` for 20 seconds at the most.
 
-The *stop* command takes a plugin name as parameter and will kill and
+The *stop* command takes a plugin name as parameter. It will kill and
 unload the specified plugin.
 
-The *startdir* command takes a directory path as parameter and will load
+The *startdir* command takes a directory path as first parameter and will
-all plugins this directory contains.
+load all plugins this directory contains. It will wait for each plugin to
+complete the handshake with `lightningd` for 20 seconds at the most.
 
 The *rescan* command starts all not-already-loaded plugins from the
 default plugins directory (by default *~/.lightning/plugins*).
@@ -32,11 +34,15 @@ The *list* command will return all the active plugins.
 RETURN VALUE
 ------------
 
-On success, this returns an array *plugins* of objects, one by plugin.
+On success, all subcommands but *stop* return an array *plugins* of
+objects, one by plugin.
 Each object contains the name of the plugin (*name* field) and its
 status (*active* boolean field). Since plugins are configured
 asynchronously, a freshly started plugin may not appear immediately.
 
+On error, the reason why the action could not be taken upon the
+plugin is returned.
+
 AUTHOR
 ------