Merge pull request lightningnetwork#8181 from ProofOfKeags/docs/compr…

…ehensive-lncli

docs/comprehensive lncli

.github/pull_request_template.md

@@ -14,6 +14,7 @@ Steps for reviewers to follow to test the change.
 - [ ] The change obeys the [Code Documentation and Commenting](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md#CodeDocumentation) guidelines, and lines wrap at 80.
 - [ ] Commits follow the [Ideal Git Commit Structure](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md#IdealGitCommitStructure).
 - [ ] Any new logging statements use an appropriate subsystem and logging level.
+- [ ] Any new lncli commands have appropriate tags in the comments for the rpc in the proto file.
 - [ ]  [There is a change description in the release notes](https://github.com/lightningnetwork/lnd/tree/master/docs/release-notes), or `[skip ci]` in the commit message for small changes.
 
-📝 Please see our  [Contribution Guidelines](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md) for further guidance.
+📝 Please see our  [Contribution Guidelines](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md) for further guidance.

.vscode/settings.json

@@ -1,4 +1,7 @@
 {
     "editor.tabSize": 8,
-    "editor.rulers": [80]
+    "editor.rulers": [
+        80
+    ],
+    "go.buildTags": "autopilotrpc chainrpc dev invoicesrpc neutrinorpc peersrpc signrpc walletrpc watchtowerrpc"
 }

cmd/lncli/commands.go

@@ -2480,7 +2480,7 @@ var verifyChanBackupCommand = cli.Command{
 
        * A packed multi-channel SCB, which couples several individual
 	 static channel backups in single blob.
-	
+
        * A file path which points to a packed single-channel backup within a
          file, using the same format that lnd does in its channel.backup file.
 

docs/release-notes/release-notes-0.18.0.md

@@ -101,6 +101,12 @@
   considered failed, thus there's no such thing as temp error for a non-MPP.
 
 ## lncli Updates
+
+* [Documented all available lncli commands](https://github.com/lightningnetwork/lnd/pull/8181).
+  This change makes all existing lncli commands have the appropriate doc tag
+  in the rpc definition to ensure that the autogenerated API documentation
+  properly specifies how to use the lncli command.
+
 ## Code Health
 
 * [Remove Litecoin code](https://github.com/lightningnetwork/lnd/pull/7867).

lnrpc/autopilotrpc/autopilot.proto

@@ -4,11 +4,29 @@ package autopilotrpc;
 
 option go_package = "github.com/lightningnetwork/lnd/lnrpc/autopilotrpc";
 
+/*
+ * Comments in this file will be directly parsed into the API
+ * Documentation as descriptions of the associated method, message, or field.
+ * These descriptions should go right above the definition of the object, and
+ * can be in either block or // comment format.
+ *
+ * An RPC method can be matched to an lncli command by placing a line in the
+ * beginning of the description in exactly the following format:
+ * lncli: `methodname`
+ *
+ * Failure to specify the exact name of the command will cause documentation
+ * generation to fail.
+ *
+ * More information on how exactly the gRPC documentation is generated from
+ * this proto file can be found here:
+ * https://github.com/lightninglabs/lightning-api
+ */
+
 // Autopilot is a service that can be used to get information about the current
 // state of the daemon's autopilot agent, and also supply it with information
 // that can be used when deciding where to open channels.
 service Autopilot {
-    /*
+    /* lncli: `autopilot status`
     Status returns whether the daemon's autopilot agent is active.
     */
     rpc Status (StatusRequest) returns (StatusResponse);
@@ -19,7 +37,7 @@ service Autopilot {
     */
     rpc ModifyStatus (ModifyStatusRequest) returns (ModifyStatusResponse);
 
-    /*
+    /* lncli: `autopilot query`
     QueryScores queries all available autopilot heuristics, in addition to any
     active combination of these heruristics, for the scores they would give to
     the given nodes.

lnrpc/autopilotrpc/autopilot.swagger.json

@@ -51,7 +51,7 @@
     },
     "/v2/autopilot/scores": {
       "get": {
-        "summary": "QueryScores queries all available autopilot heuristics, in addition to any\nactive combination of these heruristics, for the scores they would give to\nthe given nodes.",
+        "summary": "lncli: `autopilot query`\nQueryScores queries all available autopilot heuristics, in addition to any\nactive combination of these heruristics, for the scores they would give to\nthe given nodes.",
         "operationId": "Autopilot_QueryScores",
         "responses": {
           "200": {
@@ -124,7 +124,7 @@
     },
     "/v2/autopilot/status": {
       "get": {
-        "summary": "Status returns whether the daemon's autopilot agent is active.",
+        "summary": "lncli: `autopilot status`\nStatus returns whether the daemon's autopilot agent is active.",
         "operationId": "Autopilot_Status",
         "responses": {
           "200": {

lnrpc/devrpc/dev.proto

@@ -6,8 +6,26 @@ package devrpc;
 
 option go_package = "github.com/lightningnetwork/lnd/lnrpc/devrpc";
 
+/*
+ * Comments in this file will be directly parsed into the API
+ * Documentation as descriptions of the associated method, message, or field.
+ * These descriptions should go right above the definition of the object, and
+ * can be in either block or // comment format.
+ *
+ * An RPC method can be matched to an lncli command by placing a line in the
+ * beginning of the description in exactly the following format:
+ * lncli: `methodname`
+ *
+ * Failure to specify the exact name of the command will cause documentation
+ * generation to fail.
+ *
+ * More information on how exactly the gRPC documentation is generated from
+ * this proto file can be found here:
+ * https://github.com/lightninglabs/lightning-api
+ */
+
 service Dev {
-    /*
+    /* lncli: `importgraph`
     ImportGraph imports a ChannelGraph into the graph database. Should only be
     used for development.
     */

lnrpc/devrpc/dev.swagger.json

@@ -18,7 +18,7 @@
   "paths": {
     "/v2/dev/importgraph": {
       "post": {
-        "summary": "ImportGraph imports a ChannelGraph into the graph database. Should only be\nused for development.",
+        "summary": "lncli: `importgraph`\nImportGraph imports a ChannelGraph into the graph database. Should only be\nused for development.",
         "operationId": "Dev_ImportGraph",
         "responses": {
           "200": {

lnrpc/invoicesrpc/invoices.proto

@@ -6,6 +6,24 @@ package invoicesrpc;
 
 option go_package = "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc";
 
+/*
+ * Comments in this file will be directly parsed into the API
+ * Documentation as descriptions of the associated method, message, or field.
+ * These descriptions should go right above the definition of the object, and
+ * can be in either block or // comment format.
+ *
+ * An RPC method can be matched to an lncli command by placing a line in the
+ * beginning of the description in exactly the following format:
+ * lncli: `methodname`
+ *
+ * Failure to specify the exact name of the command will cause documentation
+ * generation to fail.
+ *
+ * More information on how exactly the gRPC documentation is generated from
+ * this proto file can be found here:
+ * https://github.com/lightninglabs/lightning-api
+ */
+
 // Invoices is a service that can be used to create, accept, settle and cancel
 // invoices.
 service Invoices {
@@ -17,20 +35,20 @@ service Invoices {
     rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest)
         returns (stream lnrpc.Invoice);
 
-    /*
+    /* lncli: `cancelinvoice`
     CancelInvoice cancels a currently open invoice. If the invoice is already
     canceled, this call will succeed. If the invoice is already settled, it will
     fail.
     */
     rpc CancelInvoice (CancelInvoiceMsg) returns (CancelInvoiceResp);
 
-    /*
+    /* lncli: `addholdinvoice`
     AddHoldInvoice creates a hold invoice. It ties the invoice to the hash
     supplied in the request.
     */
     rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp);
 
-    /*
+    /* lncli: `settleinvoice`
     SettleInvoice settles an accepted invoice. If the invoice is already
     settled, this call will succeed.
     */

lnrpc/invoicesrpc/invoices.swagger.json

@@ -18,7 +18,7 @@
   "paths": {
     "/v2/invoices/cancel": {
       "post": {
-        "summary": "CancelInvoice cancels a currently open invoice. If the invoice is already\ncanceled, this call will succeed. If the invoice is already settled, it will\nfail.",
+        "summary": "lncli: `cancelinvoice`\nCancelInvoice cancels a currently open invoice. If the invoice is already\ncanceled, this call will succeed. If the invoice is already settled, it will\nfail.",
         "operationId": "Invoices_CancelInvoice",
         "responses": {
           "200": {
@@ -51,7 +51,7 @@
     },
     "/v2/invoices/hodl": {
       "post": {
-        "summary": "AddHoldInvoice creates a hold invoice. It ties the invoice to the hash\nsupplied in the request.",
+        "summary": "lncli: `addholdinvoice`\nAddHoldInvoice creates a hold invoice. It ties the invoice to the hash\nsupplied in the request.",
         "operationId": "Invoices_AddHoldInvoice",
         "responses": {
           "200": {
@@ -144,7 +144,7 @@
     },
     "/v2/invoices/settle": {
       "post": {
-        "summary": "SettleInvoice settles an accepted invoice. If the invoice is already\nsettled, this call will succeed.",
+        "summary": "lncli: `settleinvoice`\nSettleInvoice settles an accepted invoice. If the invoice is already\nsettled, this call will succeed.",
         "operationId": "Invoices_SettleInvoice",
         "responses": {
           "200": {

lnrpc/lightning.proto

@@ -341,13 +341,13 @@ service Lightning {
     */
     rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse);
 
-    /*
+    /* lncli: `deletepayments`
     DeletePayment deletes an outgoing payment from DB. Note that it will not
     attempt to delete an In-Flight payment, since that would be unsafe.
     */
     rpc DeletePayment (DeletePaymentRequest) returns (DeletePaymentResponse);
 
-    /*
+    /* lncli: `deletepayments --all`
     DeleteAllPayments deletes all outgoing payments from DB. Note that it will
     not attempt to delete In-Flight payments, since that would be unsafe.
     */
@@ -479,7 +479,7 @@ service Lightning {
     rpc ExportAllChannelBackups (ChanBackupExportRequest)
         returns (ChanBackupSnapshot);
 
-    /*
+    /* lncli: `verifychanbackup`
     VerifyChanBackup allows a caller to verify the integrity of a channel backup
     snapshot. This method will accept either a packed Single or a packed Multi.
     Specifying both will result in an error.

lnrpc/lightning.swagger.json

@@ -383,7 +383,7 @@
     },
     "/v1/channels/backup/verify": {
       "post": {
-        "summary": "VerifyChanBackup allows a caller to verify the integrity of a channel backup\nsnapshot. This method will accept either a packed Single or a packed Multi.\nSpecifying both will result in an error.",
+        "summary": "lncli: `verifychanbackup`\nVerifyChanBackup allows a caller to verify the integrity of a channel backup\nsnapshot. This method will accept either a packed Single or a packed Multi.\nSpecifying both will result in an error.",
         "operationId": "Lightning_VerifyChanBackup",
         "responses": {
           "200": {
@@ -2075,7 +2075,7 @@
     },
     "/v1/payment": {
       "delete": {
-        "summary": "DeletePayment deletes an outgoing payment from DB. Note that it will not\nattempt to delete an In-Flight payment, since that would be unsafe.",
+        "summary": "lncli: `deletepayments`\nDeletePayment deletes an outgoing payment from DB. Note that it will not\nattempt to delete an In-Flight payment, since that would be unsafe.",
         "operationId": "Lightning_DeletePayment",
         "responses": {
           "200": {
@@ -2191,7 +2191,7 @@
         ]
       },
       "delete": {
-        "summary": "DeleteAllPayments deletes all outgoing payments from DB. Note that it will\nnot attempt to delete In-Flight payments, since that would be unsafe.",
+        "summary": "lncli: `deletepayments --all`\nDeleteAllPayments deletes all outgoing payments from DB. Note that it will\nnot attempt to delete In-Flight payments, since that would be unsafe.",
         "operationId": "Lightning_DeleteAllPayments",
         "responses": {
           "200": {