From 86bd45d26dcc85dfd0cfd136bd77f32973c37bbd Mon Sep 17 00:00:00 2001
From: Manuel Kieweg <manuel.kieweg@h-da.de>
Date: Mon, 12 Apr 2021 15:52:22 +0200
Subject: [PATCH] improve cli documentation
---
cmd/addDevice.go | 5 ++++-
cmd/capabilities.go | 2 +-
cmd/cli.go | 6 +++---
cmd/cliSet.go | 6 +++++-
cmd/get.go | 3 ++-
cmd/getDevice.go | 7 +++++--
cmd/getIds.go | 2 +-
cmd/init.go | 4 +++-
cmd/request.go | 7 ++++++-
cmd/requestAll.go | 6 +++++-
cmd/root.go | 12 +++++-------
11 files changed, 40 insertions(+), 20 deletions(-)
diff --git a/cmd/addDevice.go b/cmd/addDevice.go
index 3b98c03b9..27ef369d7 100644
--- a/cmd/addDevice.go
+++ b/cmd/addDevice.go
@@ -40,7 +40,10 @@ import (
var addDeviceCmd = &cobra.Command{
Use: "add-device",
Short: "adds a device to the controller",
- Long: ``,
+ Long: `Adds a device to the controller.
+
+ Device address and user credentials need to be provided
+ if they diverge from the default credentials.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(
apiEndpoint,
diff --git a/cmd/capabilities.go b/cmd/capabilities.go
index fe687884a..770435109 100644
--- a/cmd/capabilities.go
+++ b/cmd/capabilities.go
@@ -41,7 +41,7 @@ var capabilitiesCmd = &cobra.Command{
Use: "capabilities",
Short: "capabilities request",
Long: `Sends a gNMI Capabilities request to the specified target
-// and prints the supported models to stdout.`,
+ and prints the supported models to stdout.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.Capabilities(username, password, address)
},
diff --git a/cmd/cli.go b/cmd/cli.go
index e8810e534..cefb842df 100644
--- a/cmd/cli.go
+++ b/cmd/cli.go
@@ -42,8 +42,9 @@ var apiEndpoint string
// cliCmd represents the cli command
var cliCmd = &cobra.Command{
Use: "cli",
- Short: "",
- Long: ``,
+ Short: "initialises the cli",
+ Long: `Initialises the CLI. The first PND UUID and SBI UUID
+ are written to the config file for subsequent requests.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(apiEndpoint, "init")
},
@@ -52,7 +53,6 @@ var cliCmd = &cobra.Command{
func init() {
rootCmd.AddCommand(cliCmd)
- cliCmd.PersistentFlags().StringVar(&uuid, "uuid", "", "uuid of the requested device")
cliCmd.PersistentFlags().StringVar(&apiEndpoint, "api-endpoint", "http://gosdn-develop.apps.ocp.fbi.h-da.de/api", "address of the target")
}
diff --git a/cmd/cliSet.go b/cmd/cliSet.go
index 525125472..2d57f5f86 100644
--- a/cmd/cliSet.go
+++ b/cmd/cliSet.go
@@ -39,8 +39,10 @@ import (
// cliSetCmd represents the cliSet command
var cliSetCmd = &cobra.Command{
Use: "set",
+ Args: cobra.ExactArgs(2),
Short: "set a value on a device",
- Long: ``,
+ Long: `Set a path value for a given device. Only one path and
+ only one value supported for now`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(
apiEndpoint,
@@ -57,4 +59,6 @@ var cliSetCmd = &cobra.Command{
func init() {
cliCmd.AddCommand(cliSetCmd)
+
+ cliCmd.Flags().StringVar(&uuid, "uuid", "", "uuid of the requested device")
}
diff --git a/cmd/get.go b/cmd/get.go
index e2d42d80c..671f5d814 100644
--- a/cmd/get.go
+++ b/cmd/get.go
@@ -40,7 +40,8 @@ import (
var getCmd = &cobra.Command{
Use: "gosdn get",
Short: "get request",
- Long: `Sends a gNMI Get request to the specified target and prints the response to stdout`,
+ Long: `Sends a gNMI Get request to the specified target and
+ prints the response to stdout`,
RunE: func(cmd *cobra.Command, args []string) error {
_, err := cli.Get(address, username, password, args...)
return err
diff --git a/cmd/getDevice.go b/cmd/getDevice.go
index b9d3408c1..e166719f4 100644
--- a/cmd/getDevice.go
+++ b/cmd/getDevice.go
@@ -39,13 +39,16 @@ import (
// getDeviceCmd represents the getDevice command
var getDeviceCmd = &cobra.Command{
Use: "get-device",
+ Args: cobra.ExactArgs(1),
Short: "gets device information from the controller",
- Long: ``,
+ Long: `Gets device information from the controller.
+
+ Device UUID needs to be specified as positional argument.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(
apiEndpoint,
"getDevice",
- "uuid="+uuid,
+ "uuid="+args[0],
"sbi="+cliSbi,
"pnd="+cliPnd,
)
diff --git a/cmd/getIds.go b/cmd/getIds.go
index b4f0685be..ec858fd9c 100644
--- a/cmd/getIds.go
+++ b/cmd/getIds.go
@@ -40,7 +40,7 @@ import (
var getIdsCmd = &cobra.Command{
Use: "get-ids",
Short: "gets device IDs from the controller",
- Long: ``,
+ Long: `Gets device IDs from the controller and lists them.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(apiEndpoint, "getIDs")
},
diff --git a/cmd/init.go b/cmd/init.go
index 9a140f3c2..c939c2131 100644
--- a/cmd/init.go
+++ b/cmd/init.go
@@ -40,7 +40,9 @@ import (
var initCmd = &cobra.Command{
Use: "init",
Short: "initialise SBI and PND",
- Long: ``,
+ Long: `Initialise SBI and PND and saves values to config file.
+
+ Same as invoking "gosdn cli" without any arguments`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(apiEndpoint, "init")
},
diff --git a/cmd/request.go b/cmd/request.go
index 7e887b790..59edc0c5e 100644
--- a/cmd/request.go
+++ b/cmd/request.go
@@ -39,8 +39,11 @@ import (
// requestCmd represents the request command
var requestCmd = &cobra.Command{
Use: "request",
+ Args: cobra.ExactArgs(1),
Short: "requests a path from a specified device on the controller",
- Long: ``,
+ Long: `Requests a path from a specified device on the controller.
+
+ The request path is passed as positional argument.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(
apiEndpoint,
@@ -55,4 +58,6 @@ var requestCmd = &cobra.Command{
func init() {
cliCmd.AddCommand(requestCmd)
+
+ cliCmd.Flags().StringVar(&uuid, "uuid", "", "uuid of the requested device")
}
diff --git a/cmd/requestAll.go b/cmd/requestAll.go
index 183d89d4a..b4eb4650c 100644
--- a/cmd/requestAll.go
+++ b/cmd/requestAll.go
@@ -39,8 +39,12 @@ import (
// requestAllCmd represents the requestAll command
var requestAllCmd = &cobra.Command{
Use: "request-all",
+ Args: cobra.ExactArgs(1),
Short: "requests specified path from all devices on the controller",
- Long: ``,
+ Long: `Requests a path from all devices on the controller known by
+ the controller.
+
+ The request path is passed as positional argument.`,
RunE: func(cmd *cobra.Command, args []string) error {
return cli.HTTPGet(
apiEndpoint,
diff --git a/cmd/root.go b/cmd/root.go
index ca92d95ce..daf7afe31 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -32,11 +32,12 @@ POSSIBILITY OF SUCH DAMAGE.
package cmd
import (
- "code.fbi.h-da.de/cocsn/gosdn/nucleus"
"context"
+ "os"
+
+ "code.fbi.h-da.de/cocsn/gosdn/nucleus"
log "github.com/sirupsen/logrus"
"github.com/spf13/cobra"
- "os"
"github.com/spf13/viper"
)
@@ -54,7 +55,8 @@ var cliSbi string
var rootCmd = &cobra.Command{
Use: "gosdn",
Short: "starts the gosdn controller",
- Long: `Set GOSDN_DEBUG environment variable to enable debug logging.`,
+ Long: `Starts the gosdn controller and listens on port 8080
+ for REST API calls.`,
RunE: func(cmd *cobra.Command, args []string) error {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
@@ -74,10 +76,6 @@ func Execute() {
func init() {
cobra.OnInitialize(initConfig)
- // Here you will define your flags and configuration settings.
- // Cobra supports persistent flags, which, if defined here,
- // will be global for your application.
-
rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is ./configs/gosdn.toml)")
rootCmd.PersistentFlags().StringVarP(&username, "username", "u", "admin", "username for a gnmi resource")
rootCmd.PersistentFlags().StringVarP(&password, "password", "p", "arista", "password for a gnmi resource")
--
GitLab