Merge pull request #45 from spinkube/docs-improvements

make docstrings more consistent

pkg/cmd/connect.go

@@ -18,8 +18,8 @@ import (
 const spinAppPort = "80"
 
 var connectCmd = &cobra.Command{
-	Use:    "connect [<app-name>]",
-	Short:  "connect to spin app locally",
+	Use:    "connect <name>",
+	Short:  "Establish a connection to a running application",
 	Hidden: isExperimentalFlagNotSet,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var appName string
@@ -36,7 +36,7 @@ var connectCmd = &cobra.Command{
 		labelSelector, _ := cmd.Flags().GetString("label-selector")
 
 		if appName == "" && fieldSelector == "" && labelSelector == "" {
-			return fmt.Errorf("either one of app-name or fieldSelector or labelSelector is required")
+			return fmt.Errorf("either one of <name>, --field-selector, or --label-selector is required")
 		}
 
 		getPodTimeout, err := cmdutil.GetPodRunningTimeoutFlag(cmd)
@@ -58,7 +58,7 @@ var connectCmd = &cobra.Command{
 		}
 
 		if len(resp.Items) == 0 {
-			return fmt.Errorf("no active deployment found for SpinApp")
+			return fmt.Errorf("no active deployment found for the given application name or selector")
 		}
 
 		var deploy appsv1.Deployment
@@ -107,7 +107,7 @@ func init() {
 	cmdutil.AddPodRunningTimeoutFlag(connectCmd, 30*time.Second)
 	configFlags.AddFlags(connectCmd.Flags())
 
-	connectCmd.Flags().StringP("local-port", "p", "", "local port to listen on when connecting to SpinApp")
+	connectCmd.Flags().StringP("local-port", "p", "", "The local port to listen on when connecting to SpinApp")
 	connectCmd.Flags().String("field-selector", "", "Selector (field query) to filter on, supports '=', '==', and '!='.(e.g. --field-selector key1=value1,key2=value2). The server only supports a limited number of field queries per type.")
 	connectCmd.Flags().StringP("selector", "l", "", "Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2). Matching objects must satisfy all of the specified label constraints.")
 

pkg/cmd/delete.go

@@ -11,8 +11,8 @@ import (
 )
 
 var deleteCmd = &cobra.Command{
-	Use:    "delete app-name",
-	Short:  "Delete app",
+	Use:    "delete <name>",
+	Short:  "Delete the application",
 	Hidden: isExperimentalFlagNotSet,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var appName string
@@ -21,7 +21,7 @@ var deleteCmd = &cobra.Command{
 		}
 
 		if appName == "" {
-			return fmt.Errorf("no app name specified to delete")
+			return fmt.Errorf("no application name specified to delete")
 		}
 
 		yes, err := cmd.Flags().GetBool("yes")
@@ -48,7 +48,7 @@ var deleteCmd = &cobra.Command{
 		err = k8simpl.DeleteSpinApp(context.TODO(), okey)
 		if err != nil {
 			if apierrors.IsNotFound(err) {
-				fmt.Printf("Could not find app with name %s\n", appName)
+				fmt.Printf("Could not find application with name %s\n", appName)
 				os.Exit(1)
 			}
 
@@ -64,6 +64,6 @@ var deleteCmd = &cobra.Command{
 func init() {
 	configFlags.AddFlags(deleteCmd.Flags())
 
-	deleteCmd.Flags().BoolP("yes", "y", false, "specify --yes to immediately delete the resource")
+	deleteCmd.Flags().BoolP("yes", "y", false, "specify --yes to immediately delete the application")
 	rootCmd.AddCommand(deleteCmd)
 }

pkg/cmd/deploy.go

@@ -20,7 +20,7 @@ var (
 
 var deployCmd = &cobra.Command{
 	Use:    "deploy",
-	Short:  "deploy spin app",
+	Short:  "Deploy application to Kubernetes",
 	Hidden: isExperimentalFlagNotSet,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		reference := strings.Split(artifact, ":")[0]
@@ -60,9 +60,9 @@ var deployCmd = &cobra.Command{
 }
 
 func init() {
-	deployCmd.Flags().BoolVar(&dryRun, "dry-run", false, "only print the SpinApp resource file without deploying")
-	deployCmd.Flags().Int32VarP(&replicas, "replicas", "r", 2, "Number of replicas for the spin app")
-	deployCmd.Flags().StringVarP(&artifact, "from", "f", "", "Reference in the registry of the Spin application")
+	deployCmd.Flags().BoolVar(&dryRun, "dry-run", false, "only print the kubernetes manifest without deploying")
+	deployCmd.Flags().Int32VarP(&replicas, "replicas", "r", 2, "Number of replicas for the application")
+	deployCmd.Flags().StringVarP(&artifact, "from", "f", "", "Reference in the registry of the application")
 	deployCmd.MarkFlagRequired("from")
 
 	configFlags.AddFlags(deployCmd.Flags())

pkg/cmd/get.go

@@ -9,8 +9,8 @@ import (
 )
 
 var getCmd = &cobra.Command{
-	Use:    "get [app-name]",
-	Short:  "Display detailed information about an app",
+	Use:    "get <name>",
+	Short:  "Display detailed application information",
 	Hidden: isExperimentalFlagNotSet,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var appName string

pkg/cmd/list.go

@@ -9,7 +9,7 @@ import (
 
 var listCmd = &cobra.Command{
 	Use:    "list",
-	Short:  "List apps",
+	Short:  "List applications",
 	Hidden: isExperimentalFlagNotSet,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		appsResp, err := k8simpl.ListSpinApps(context.TODO(), namespace)

pkg/cmd/logs.go

@@ -11,8 +11,8 @@ import (
 var logOpts *logs.LogsOptions
 
 var logsCmd = &cobra.Command{
-	Use:    "logs [<app-name>]",
-	Short:  "print the logs for a SpinApp",
+	Use:    "logs <name>",
+	Short:  "Display application logs",
 	Hidden: isExperimentalFlagNotSet,
 	Run: func(cmd *cobra.Command, args []string) {
 		var appName string

pkg/cmd/root.go

@@ -27,7 +27,7 @@ var rootCmd = newRootCmd()
 func newRootCmd() *cobra.Command {
 	rootCmd := &cobra.Command{
 		Use:     "k8s",
-		Short:   "Manage apps running on Kubernetes",
+		Short:   "Manage applications running on Kubernetes",
 		Version: Version,
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			namespace = getNamespace(configFlags)

pkg/cmd/scaffold.go

@@ -152,7 +152,7 @@ spec:
 
 var scaffoldCmd = &cobra.Command{
 	Use:   "scaffold",
-	Short: "scaffold SpinApp manifest",
+	Short: "Scaffold application manifest",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		content, err := scaffold(scaffoldOpts)
 		if err != nil {
@@ -165,7 +165,7 @@ var scaffoldCmd = &cobra.Command{
 				return err
 			}
 
-			log.Printf("\nSpinApp manifest saved to %s\n", scaffoldOpts.output)
+			log.Printf("\nApplication manifest saved to %s\n", scaffoldOpts.output)
 			return nil
 
 		}
@@ -286,20 +286,20 @@ func validateImageReference(imageRef string) bool {
 }
 
 func init() {
-	scaffoldCmd.Flags().Int32VarP(&scaffoldOpts.replicas, "replicas", "r", 2, "Minimum number of replicas for the spin app")
-	scaffoldCmd.Flags().Int32Var(&scaffoldOpts.maxReplicas, "max-replicas", 3, "Maximum number of replicas for the spin app. Autoscaling must be enabled to use this flag")
+	scaffoldCmd.Flags().Int32VarP(&scaffoldOpts.replicas, "replicas", "r", 2, "Minimum number of replicas for the application")
+	scaffoldCmd.Flags().Int32Var(&scaffoldOpts.maxReplicas, "max-replicas", 3, "Maximum number of replicas for the application. Autoscaling must be enabled to use this flag")
 	scaffoldCmd.Flags().Int32Var(&scaffoldOpts.targetCpuUtilizationPercentage, "autoscaler-target-cpu-utilization", 60, "The target CPU utilization percentage to maintain across all pods")
 	scaffoldCmd.Flags().Int32Var(&scaffoldOpts.targetMemoryUtilizationPercentage, "autoscaler-target-memory-utilization", 60, "The target memory utilization percentage to maintain across all pods")
 	scaffoldCmd.Flags().StringVar(&scaffoldOpts.autoscaler, "autoscaler", "", "The autoscaler to use. Valid values are 'hpa' and 'keda'")
-	scaffoldCmd.Flags().StringVar(&scaffoldOpts.executor, "executor", "containerd-shim-spin", "The executor used to run the Spin application")
-	scaffoldCmd.Flags().StringVar(&scaffoldOpts.cpuLimit, "cpu-limit", "", "The maximum amount of CPU resource units the Spin application is allowed to use")
-	scaffoldCmd.Flags().StringVar(&scaffoldOpts.cpuRequest, "cpu-request", "", "The amount of CPU resource units requested by the Spin application. Used to determine which node the Spin application will run on")
-	scaffoldCmd.Flags().StringVar(&scaffoldOpts.memoryLimit, "memory-limit", "", "The maximum amount of memory the Spin application is allowed to use")
-	scaffoldCmd.Flags().StringVar(&scaffoldOpts.memoryRequest, "memory-request", "", "The amount of memory requested by the Spin application. Used to determine which node the Spin application will run on")
-	scaffoldCmd.Flags().StringVarP(&scaffoldOpts.from, "from", "f", "", "Reference in the registry of the Spin application")
-	scaffoldCmd.Flags().StringVarP(&scaffoldOpts.output, "out", "o", "", "path to file to write manifest yaml")
-	scaffoldCmd.Flags().StringVarP(&scaffoldOpts.configfile, "runtime-config-file", "c", "", "path to runtime config file")
-	scaffoldCmd.Flags().StringSliceVarP(&scaffoldOpts.imagePullSecrets, "image-pull-secret", "s", []string{}, "secrets in the same namespace to use for pulling the image")
+	scaffoldCmd.Flags().StringVar(&scaffoldOpts.executor, "executor", "containerd-shim-spin", "The executor used to run the application")
+	scaffoldCmd.Flags().StringVar(&scaffoldOpts.cpuLimit, "cpu-limit", "", "The maximum amount of CPU resource units the application is allowed to use")
+	scaffoldCmd.Flags().StringVar(&scaffoldOpts.cpuRequest, "cpu-request", "", "The amount of CPU resource units requested by the application. Used to determine which node the application will run on")
+	scaffoldCmd.Flags().StringVar(&scaffoldOpts.memoryLimit, "memory-limit", "", "The maximum amount of memory the application is allowed to use")
+	scaffoldCmd.Flags().StringVar(&scaffoldOpts.memoryRequest, "memory-request", "", "The amount of memory requested by the application. Used to determine which node the application will run on")
+	scaffoldCmd.Flags().StringVarP(&scaffoldOpts.from, "from", "f", "", "Reference in the registry of the application")
+	scaffoldCmd.Flags().StringVarP(&scaffoldOpts.output, "out", "o", "", "Path to file to write manifest yaml")
+	scaffoldCmd.Flags().StringVarP(&scaffoldOpts.configfile, "runtime-config-file", "c", "", "Path to runtime config file")
+	scaffoldCmd.Flags().StringSliceVarP(&scaffoldOpts.imagePullSecrets, "image-pull-secret", "s", []string{}, "Secrets in the same namespace to use for pulling the image")
 
 	scaffoldCmd.MarkFlagRequired("from")