From bba09e320c125933d667a62c43bc553ccd0b99a1 Mon Sep 17 00:00:00 2001 From: Keagan McClelland Date: Tue, 14 Nov 2023 17:02:54 -0800 Subject: [PATCH] lnrpc: add invoicesrpc doc tags to enable lncli api doc generation --- lnrpc/invoicesrpc/invoices.proto | 24 +++++++++++++++++++++--- lnrpc/invoicesrpc/invoices.swagger.json | 6 +++--- lnrpc/invoicesrpc/invoices_grpc.pb.go | 6 ++++++ 3 files changed, 30 insertions(+), 6 deletions(-) diff --git a/lnrpc/invoicesrpc/invoices.proto b/lnrpc/invoicesrpc/invoices.proto index 12317d02c..db9907a60 100644 --- a/lnrpc/invoicesrpc/invoices.proto +++ b/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. */ diff --git a/lnrpc/invoicesrpc/invoices.swagger.json b/lnrpc/invoicesrpc/invoices.swagger.json index 8452e9972..eaf51fd89 100644 --- a/lnrpc/invoicesrpc/invoices.swagger.json +++ b/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": { diff --git a/lnrpc/invoicesrpc/invoices_grpc.pb.go b/lnrpc/invoicesrpc/invoices_grpc.pb.go index 9284d4b0b..bc2f24ac1 100644 --- a/lnrpc/invoicesrpc/invoices_grpc.pb.go +++ b/lnrpc/invoicesrpc/invoices_grpc.pb.go @@ -23,13 +23,16 @@ type InvoicesClient interface { // to notify the client of state transitions of the specified invoice. // Initially the current invoice state is always sent out. SubscribeSingleInvoice(ctx context.Context, in *SubscribeSingleInvoiceRequest, opts ...grpc.CallOption) (Invoices_SubscribeSingleInvoiceClient, error) + // 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. CancelInvoice(ctx context.Context, in *CancelInvoiceMsg, opts ...grpc.CallOption) (*CancelInvoiceResp, error) + // lncli: `addholdinvoice` // AddHoldInvoice creates a hold invoice. It ties the invoice to the hash // supplied in the request. AddHoldInvoice(ctx context.Context, in *AddHoldInvoiceRequest, opts ...grpc.CallOption) (*AddHoldInvoiceResp, error) + // lncli: `settleinvoice` // SettleInvoice settles an accepted invoice. If the invoice is already // settled, this call will succeed. SettleInvoice(ctx context.Context, in *SettleInvoiceMsg, opts ...grpc.CallOption) (*SettleInvoiceResp, error) @@ -122,13 +125,16 @@ type InvoicesServer interface { // to notify the client of state transitions of the specified invoice. // Initially the current invoice state is always sent out. SubscribeSingleInvoice(*SubscribeSingleInvoiceRequest, Invoices_SubscribeSingleInvoiceServer) error + // 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. CancelInvoice(context.Context, *CancelInvoiceMsg) (*CancelInvoiceResp, error) + // lncli: `addholdinvoice` // AddHoldInvoice creates a hold invoice. It ties the invoice to the hash // supplied in the request. AddHoldInvoice(context.Context, *AddHoldInvoiceRequest) (*AddHoldInvoiceResp, error) + // lncli: `settleinvoice` // SettleInvoice settles an accepted invoice. If the invoice is already // settled, this call will succeed. SettleInvoice(context.Context, *SettleInvoiceMsg) (*SettleInvoiceResp, error)