Merge pull request #671 from nonfungible-human/issue591

main: make cmd documentation coherent

Author: ViktorTigerstrom

cmd/litcli/accounts.go

@@ -22,7 +22,7 @@ var accountsCommands = []cli.Command{
 	{
 		Name:      "accounts",
 		ShortName: "a",
-		Usage:     "manage accounts",
+		Usage:     "Manage accounts",
 		Category:  "Accounts",
 		Subcommands: []cli.Command{
 			createAccountCommand,
@@ -31,6 +31,7 @@ var accountsCommands = []cli.Command{
 			accountInfoCommand,
 			removeAccountCommand,
 		},
+		Description: "Manage accounts.",
 	},
 }
 
@@ -39,38 +40,38 @@ var createAccountCommand = cli.Command{
 	ShortName: "c",
 	Usage:     "Create a new off-chain account with a balance.",
 	ArgsUsage: "balance [expiration_date] [--label=LABEL] [--save_to=FILE]",
-	Description: `
-	Adds an entry to the account database. This entry represents an amount
-	of satoshis (account balance) that can be spent using off-chain
-	transactions (e.g. paying invoices).
-
-	Macaroons can be created to be locked to an account. This makes sure
-	that the bearer of the macaroon can only spend at most that amount of
-	satoshis through the daemon that has issued the macaroon.
-
-	Accounts only assert a maximum amount spendable. Having a certain
-	account balance does not guarantee that the node has the channel
-	liquidity to actually spend that amount.
-	`,
+	Description: "Adds an entry to the account database. " +
+		"This entry represents an amount of satoshis (account " +
+		"balance) that can be spent using off-chain transactions " +
+		"(e.g. paying invoices).\n\n" +
+
+		"   Macaroons can be created to be locked to an account. " +
+		"This makes sure that the bearer of the macaroon can only " +
+		"spend at most that amount of satoshis through the daemon " +
+		"that has issued the macaroon.\n\n" +
+
+		"   Accounts only assert a maximum amount spendable. Having " +
+		"a certain account balance does not guarantee that the node " +
+		"has the channel liquidity to actually spend that amount.",
 	Flags: []cli.Flag{
 		cli.Uint64Flag{
 			Name:  "balance",
-			Usage: "the initial balance of the account",
+			Usage: "The initial balance of the account.",
 		},
 		cli.Int64Flag{
 			Name: "expiration_date",
-			Usage: "the expiration date of the account expressed " +
+			Usage: "The expiration date of the account expressed " +
 				"in seconds since the unix epoch. 0 means " +
-				"it does not expire",
+				"it does not expire.",
 		},
 		cli.StringFlag{
 			Name: "save_to",
-			Usage: "store the account macaroon created for the " +
-				"account to the given file",
+			Usage: "Store the account macaroon created for the " +
+				"account to the given file.",
 		},
 		cli.StringFlag{
 			Name:  labelName,
-			Usage: "(optional) the unique label of the account",
+			Usage: "(optional) The unique label of the account.",
 		},
 	},
 	Action: createAccount,
@@ -152,31 +153,29 @@ var updateAccountCommand = cli.Command{
 	ShortName: "u",
 	Usage:     "Update an existing off-chain account.",
 	ArgsUsage: "[id | label] new_balance [new_expiration_date] [--save_to=]",
-	Description: `
-	Updates an existing off-chain account and sets either a new balance or
-	new expiration date or both.
-	`,
+	Description: "Updates an existing off-chain account and sets " +
+		"either a new balance or new expiration date or both.",
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  idName,
-			Usage: "the ID of the account to update",
+			Usage: "The ID of the account to update.",
 		},
 		cli.StringFlag{
 			Name:  labelName,
-			Usage: "(optional) the unique label of the account",
+			Usage: "(optional) The unique label of the account.",
 		},
 		cli.Int64Flag{
 			Name: "new_balance",
-			Usage: "the new balance of the account; -1 means do " +
-				"not update the balance",
+			Usage: "The new balance of the account; -1 means do " +
+				"not update the balance.",
 			Value: -1,
 		},
 		cli.Int64Flag{
 			Name: "new_expiration_date",
-			Usage: "the new expiration date of the account " +
+			Usage: "The new expiration date of the account " +
 				"expressed in seconds since the unix epoch; " +
 				"-1 means do not update the expiration date; " +
-				"0 means it does not expire",
+				"0 means it does not expire.",
 			Value: -1,
 		},
 	},
@@ -243,11 +242,9 @@ func updateAccount(ctx *cli.Context) error {
 var listAccountsCommand = cli.Command{
 	Name:      "list",
 	ShortName: "l",
-	Usage:     "Lists all off-chain accounts.",
-	Description: `
-	Returns all accounts that are currently stored in the account
-	database.
-	`,
+	Usage:     "List all off-chain accounts.",
+	Description: "Returns all accounts that are currently stored in " +
+		"the account database.",
 	Action: listAccounts,
 }
 
@@ -275,17 +272,16 @@ var accountInfoCommand = cli.Command{
 	ShortName: "i",
 	Usage:     "Show information about a single off-chain account.",
 	ArgsUsage: "[id | label]",
-	Description: `
-	Returns a single account entry from the account database.
-	`,
+	Description: "Returns a single account entry from the account " +
+		"database.",
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  idName,
-			Usage: "the ID of the account",
+			Usage: "The ID of the account.",
 		},
 		cli.StringFlag{
 			Name:  labelName,
-			Usage: "(optional) the unique label of the account",
+			Usage: "(optional) The unique label of the account.",
 		},
 	},
 	Action: accountInfo,
@@ -321,19 +317,17 @@ func accountInfo(ctx *cli.Context) error {
 var removeAccountCommand = cli.Command{
 	Name:      "remove",
 	ShortName: "r",
-	Usage:     "Removes an off-chain account from the database.",
+	Usage:     "Remove an off-chain account from the database.",
 	ArgsUsage: "[id | label]",
-	Description: `
-	Removes an account entry from the account database.
-	`,
+	Description: "Removes an account entry from the account database.",
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  idName,
-			Usage: "the ID of the account",
+			Usage: "The ID of the account.",
 		},
 		cli.StringFlag{
 			Name:  labelName,
-			Usage: "(optional) the unique label of the account",
+			Usage: "(optional) The unique label of the account.",
 		},
 	},
 	Action: removeAccount,

cmd/litcli/actions.go

@@ -12,6 +12,7 @@ import (
 var listActionsCommand = cli.Command{
 	Name:   "actions",
 	Usage:  "List actions performed on the Litd server",
+	Category: "Firewall",
 	Action: listActions,
 	Flags: []cli.Flag{
 		cli.StringFlag{
@@ -53,22 +54,22 @@ var listActionsCommand = cli.Command{
 			Name: "state",
 			Usage: "The action state to filter on. If not set, " +
 				"then actions of any state will be returned. " +
-				"Options include: 'pending', 'done' and 'error",
+				"Options include: 'pending', 'done' and 'error'.",
 		},
 		cli.Uint64Flag{
 			Name: "index_offset",
 			Usage: "The index of an action that will be used as " +
-				"either the start a query to determine which " +
-				"actions should be returned in the response",
+				"the start of a query to determine which " +
+				"actions should be returned in the response.",
 		},
 		cli.Uint64Flag{
 			Name:  "max_num_actions",
-			Usage: "The max number of actions to return",
+			Usage: "The max number of actions to return.",
 		},
 		cli.BoolFlag{
 			Name: "oldest_first",
-			Usage: "Tf set, actions succeeding the index_offset " +
-				"will be returned",
+			Usage: "If set, actions succeeding the index_offset " +
+				"will be returned.",
 		},
 		cli.BoolFlag{
 			Name: "count_total",

cmd/litcli/autopilot.go

@@ -16,35 +16,33 @@ import (
 
 var autopilotCommands = cli.Command{
 	Name:     "autopilot",
-	Usage:    "manage autopilot sessions",
-	Category: "Autopilot",
+	Usage:    "Manage autopilot sessions",
+	Category: "LNC",
 	Subcommands: []cli.Command{
 		listAutopilotFeaturesCmd,
 		addAutopilotSessionCmd,
 		revokeAutopilotSessionCmd,
 		listAutopilotSessionsCmd,
 	},
+	Description: "Manage autopilot sessions.",
 }
 
 var listAutopilotFeaturesCmd = cli.Command{
 	Name:      "features",
 	ShortName: "f",
 	Usage:     "List available Autopilot features.",
-	Description: `
-	List available Autopilot features.	
-	`,
+	Description: "List available Autopilot features.",
 	Action: listFeatures,
 }
 
 var addAutopilotSessionCmd = cli.Command{
 	Name:      "add",
 	ShortName: "a",
 	Usage:     "Initialize an Autopilot session.",
-	Description: `
-	Initialize an Autopilot session.
-
-	If set for any feature, configuration flags need to be repeated for each
-	feature that is registered, corresponding to the order of features.`,
+	Description: "Initialize an Autopilot session.\n\n" +
+		"   If set for any feature, configuration flags need to be " +
+		"repeated for each feature that is registered, corresponding " +
+		"to the order of features.",
 	Action: initAutopilotSession,
 	Flags: []cli.Flag{
 		labelFlag,
@@ -57,31 +55,31 @@ var addAutopilotSessionCmd = cli.Command{
 		},
 		cli.StringFlag{
 			Name: "channel-restrict-list",
-			Usage: "list of channel IDs that the " +
+			Usage: "List of channel IDs that the " +
 				"Autopilot server should not " +
 				"perform actions on. In the " +
 				"form of: chanID1,chanID2,...",
 		},
 		cli.StringFlag{
 			Name: "peer-restrict-list",
-			Usage: "list of peer IDs that the " +
+			Usage: "List of peer IDs that the " +
 				"Autopilot server should not " +
 				"perform actions on. In the " +
 				"form of: peerID1,peerID2,...",
 		},
 		cli.StringFlag{
 			Name: "group_id",
 			Usage: "The hex encoded group ID of the session " +
-				"group to link this one to",
+				"group to link this one to.",
 		},
 		cli.StringSliceFlag{
 			Name: "feature-config",
-			Usage: `JSON-serialized configuration with the ` +
-				`expected format: {"version":0,` +
-				`"option1":"parameter1",` +
-				`"option2":"parameter2",...}. An empty ` +
-				`configuration is allowed with {} to use the ` +
-				`default configuration`,
+			Usage: "JSON-serialized configuration with the " +
+				"expected format: {\"version\":0," +
+				"\"option1\":\"parameter1\"," +
+				"\"option2\":\"parameter2\",...}. An empty " +
+				"configuration is allowed with {} to use the " +
+				"default configuration.",
 		},
 	},
 }
@@ -90,15 +88,13 @@ var revokeAutopilotSessionCmd = cli.Command{
 	Name:      "revoke",
 	ShortName: "r",
 	Usage:     "Revoke an Autopilot session.",
-	Description: `
-	Revoke an active Autopilot session.
-	`,
+	Description: "Revoke an active Autopilot session.",
 	Action: revokeAutopilotSession,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name: "localpubkey",
-			Usage: "local pubkey of the " +
-				"session to revoke",
+			Usage: "Local pubkey of the " +
+				"session to revoke.",
 			Required: true,
 		},
 	},
@@ -108,9 +104,7 @@ var listAutopilotSessionsCmd = cli.Command{
 	Name:      "list",
 	ShortName: "l",
 	Usage:     "List all Autopilot sessions.",
-	Description: `
-	List all Autopilot sessions.
-	`,
+	Description: "List all Autopilot sessions.\n",
 	Action: listAutopilotSessions,
 }
 

cmd/litcli/helpers.go

@@ -14,9 +14,10 @@ import (
 // helperCommands are commands that do not require a connection to LiTd to
 // return a response.
 var helperCommands = cli.Command{
-	Name:     "helper",
-	Usage:    "helper commands",
-	Category: "Helper",
+	Name:        "helper",
+	Usage:       "Helper commands",
+	Description: "Helper commands.",
+	Category:     "LiT",
 	Subcommands: []cli.Command{
 		generateSuperMacRootIDCmd,
 		isSuperMacaroonCmd,
@@ -27,21 +28,20 @@ var helperCommands = cli.Command{
 // key ID for a super macaroon. A suffix may be specified.
 var generateSuperMacRootIDCmd = cli.Command{
 	Name: "supermacrootkey",
-	Usage: "Generate a valid super macaroon root key ID from scratch " +
-		"or from a given root key ID suffix",
-	Description: `
-	This command can be used to generate a valid super macaroon root key ID
-	from scratch or from a given root key ID suffix.
-	`,
+	Usage: "Generate a valid super macaroon root key ID from " +
+		"scratch or from a given root key ID suffix.",
+	Description: "This command can be used to generate a valid " +
+		"super macaroon root key ID from scratch or from " +
+		"a given root key ID suffix.",
 	Action: superMacRootKey,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name: "root_key_suffix",
 			Usage: "A 4-byte suffix to use in the construction " +
 				"of the root key ID. If not provided, then a " +
 				"random one will be generated. This must be " +
-				"specified as a hex string using a maximum of " +
-				"8 characters.",
+				"specified as a hex string using a maximum " +
+				"of 8 characters.",
 		},
 	},
 }
@@ -81,16 +81,14 @@ func superMacRootKey(ctx *cli.Context) error {
 // a macaroon is a super macaroon.
 var isSuperMacaroonCmd = cli.Command{
 	Name:  "issupermacaroon",
-	Usage: "Prints 'true' if the given macaroon is a super macaroon",
-	Description: `
-	This command can be used to verify if a macaroon is considered a 
-	super macaroon.
-	`,
+	Usage: "Prints 'true' if the given macaroon is a super macaroon.",
+	Description: "This command can be used to verify if a macaroon is " +
+		"considered a super macaroon.",
 	Action: isSuperMacaroon,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:     "mac",
-			Usage:    "The hex-encoded macaroon",
+			Usage:    "The hex-encoded macaroon.",
 			Required: true,
 		},
 	},