chore: Update help messages and adding examples. (#218)

* chore: Update help messages and adding examples.

This commit introduces fixes for the top-level help message as described in #187.

It does not address:

* #216 - Use `kn function` in help message when run as a plugin to kn
* #215 - Group main help message to put important commands to the top
* #214 - Make examples in usage message parameterizable

Author: rhuss

Diff for: cmd/build.go

@@ -13,36 +13,43 @@ import (
 
 func init() {
 	root.AddCommand(buildCmd)
-	buildCmd.Flags().StringP("builder", "b", "default", "Buildpacks builder")
-	buildCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FUNC_CONFIRM")
-	buildCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --registry) - $FUNC_IMAGE")
-	buildCmd.Flags().StringP("path", "p", cwd(), "Path to the Function project directory - $FUNC_PATH")
-	buildCmd.Flags().StringP("registry", "r", "", "Registry for built images, ex 'docker.io/myuser' or just 'myuser'.  Optional if --image provided. - $FUNC_REGISTRY")
+	buildCmd.Flags().StringP("builder", "b", "default", "Buildpack builder, either an as a an image name or a mapping name as defined in func.yaml")
+	buildCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)")
+	buildCmd.Flags().StringP("image", "i", "", "Full image name in the orm [registry]/[namespace]/[name]:[tag] (optional). This option takes precedence over --registry (Env: $FUNC_IMAGE")
+	buildCmd.Flags().StringP("path", "p", cwd(), "Path to the project directory (Env: $FUNC_PATH)")
+	buildCmd.Flags().StringP("registry", "r", "", "Registry + namespace part of the image to build, ex 'quay.io/myuser'.  The full image name is automatically determined based on the local directory name. If not provided the registry will be taken from func.yaml (Env: $FUNC_REGISTRY)")
 
 	err := buildCmd.RegisterFlagCompletionFunc("builder", CompleteBuilderList)
 	if err != nil {
-		fmt.Println("Error while calling RegisterFlagCompletionFunc: ", err)
+		fmt.Println("internal: error while calling RegisterFlagCompletionFunc: ", err)
 	}
 }
 
 var buildCmd = &cobra.Command{
 	Use:   "build",
-	Short: "Build an existing Function project as an OCI image",
-	Long: `Build an existing Function project as an OCI image
-
-Builds the Function project in the current directory or in the directory
-specified by the --path flag. The func.yaml file is read to determine the
-image name and registry. If both of these values are unset in the
-configuration file the --registry or -r flag should be provided and an image
-name will be derived from the project name.
-
-Any value provided for the --image flag will be persisted in the func.yaml
-configuration file. On subsequent invocations of the "build" command
-these values will be read from the configuration file.
-
-It's possible to use a custom Buildpack builder with the --builder flag.
-The value may be image name e.g. "cnbs/sample-builder:bionic",
-or reference to builderMaps in the config file e.g. "default".
+	Short: "Build a function project as a container image",
+	Long: `Build a function project as a container image
+
+This command builds the function project in the current directory or in the directory
+specified by --path. The result will be a container image that is pushed to a registry.
+The func.yaml file is read to determine the image name and registry. 
+If the project has not already been built, either --registry or --image must be provided 
+and the image name is stored in the configuration file.
+`,
+    Example: `
+# Build from the local directory, using the given registry as target.
+# The full image name will be determined automatically based on the
+# project directory name
+kn func build --registry quay.io/myuser
+
+# Build from the local directory, specifying the full image name
+kn func build --image quay.io/myuser/myfunc
+
+# Re-build, picking up a previously supplied image name from a local func.yml
+kn func build
+
+# Build with a custom buildpack builder
+kn func build --builder cnbs/sample-builder:bionic
 `,
 	SuggestFor: []string{"biuld", "buidl", "built"},
 	PreRunE:    bindEnv("image", "path", "builder", "registry", "confirm"),
@@ -59,18 +66,18 @@ func runBuild(cmd *cobra.Command, _ []string) (err error) {
 
 	// Check if the Function has been initialized
 	if !function.Initialized() {
-		return fmt.Errorf("the given path '%v' does not contain an initialized Function. Please create one at this path before deploying.", config.Path)
+		return fmt.Errorf("the given path '%v' does not contain an initialized function. Please create one at this path before deploying", config.Path)
 	}
 
 	// If the Function does not yet have an image name and one was not provided on the command line
 	if function.Image == "" {
 		//  AND a --registry was not provided, then we need to
 		// prompt for a registry from which we can derive an image name.
 		if config.Registry == "" {
-			fmt.Print("A registry for Function images is required. For example, 'docker.io/tigerteam'.\n\n")
-			config.Registry = prompt.ForString("Registry for Function images", "")
+			fmt.Print("A registry for function images is required (e.g. 'quay.io/boson').\n\n")
+			config.Registry = prompt.ForString("Registry for function images", "")
 			if config.Registry == "" {
-				return fmt.Errorf("Unable to determine Function image name")
+				return fmt.Errorf("unable to determine function image name")
 			}
 		}
 
@@ -142,7 +149,7 @@ func (c buildConfig) Prompt() buildConfig {
 	}
 	return buildConfig{
 		Path:    prompt.ForString("Path to project directory", c.Path),
-		Image:   prompt.ForString("Image name", imageName, prompt.WithRequired(true)),
+		Image:   prompt.ForString("Full image name (e.g. quay.io/boson/node-sample)", imageName, prompt.WithRequired(true)),
 		Verbose: c.Verbose,
 		// Registry not prompted for as it would be confusing when combined with explicit image.  Instead it is
 		// inferred by the derived default for Image, which uses Registry for derivation.

Diff for: cmd/completion.go

@@ -14,7 +14,7 @@ func init() {
 // completionCmd represents the completion command
 var completionCmd = &cobra.Command{
 	Use:   "completion <bash|zsh|fish>",
-	Short: "Generate bash/zsh completion scripts",
+	Short: "Generate completion scripts for bash, fish and zsh",
 	Long: `To load completion run
 
 For zsh:

Diff for: cmd/create.go

@@ -13,31 +13,36 @@ import (
 
 func init() {
 	root.AddCommand(createCmd)
-	createCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FUNC_CONFIRM")
-	createCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. Default runtime is 'node'. Available runtimes: 'node', 'quarkus' and 'go'. - $FUNC_RUNTIME")
-	createCmd.Flags().StringP("templates", "", filepath.Join(configPath(), "templates"), "Extensible templates path. - $FUNC_TEMPLATES")
-	createCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger. Default trigger is 'http'. Available triggers: 'http' and 'events' - $FUNC_TRIGGER")
+	createCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)")
+	createCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. Available runtimes: 'node', 'quarkus' and 'go' (Env: $FUNC_RUNTIME)")
+	createCmd.Flags().StringP("templates", "", filepath.Join(configPath(), "templates"), "Path to additional templates (Env: $FUNC_TEMPLATES)")
+	createCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger. Available triggers: 'http' and 'events' (Env: $FUNC_TRIGGER)")
 
 	if err := createCmd.RegisterFlagCompletionFunc("runtime", CompleteRuntimeList); err != nil {
-		fmt.Println("Error while calling RegisterFlagCompletionFunc: ", err)
+		fmt.Println("internal: error while calling RegisterFlagCompletionFunc: ", err)
 	}
 }
 
 var createCmd = &cobra.Command{
-	Use:   "create <path>",
-	Short: "Create a new Function project",
-	Long: `Create a new Function project
+	Use:   "create [PATH]",
+	Short: "Create a function project",
+	Long: `Create a function project
 
-Creates a new Function project at <path>. If <path> does not exist, it is
-created. The Function name is the name of the leaf directory at <path>.
-
-A project for a Node.js Function will be created by default. Specify an
-alternate runtime with the --language or -l flag. Available alternates are
-"quarkus" and "go".
-
-Use the --trigger or -t flag to specify the function invocation context.
-By default, the trigger is "http". To create a Function for CloudEvents, use
-"events".
+Creates a new function project in PATH, or in the current directory if no PATH is given. 
+The name of the project is determined by the directory name the project is created in.
+`,
+	Example: `
+# Create a Node.js function project in the current directory, choosing the
+# directory name as the project's name.
+kn func create
+
+# Create a Quarkus function project in the directory "sample-service". 
+# The directory will be created in the local directory if non-existent and 
+# the project is called "sample-service"
+kn func create --runtime quarkus myfunc
+
+# Create a function project that uses a CloudEvent based function signature
+kn func create --trigger events myfunc
 `,
 	SuggestFor: []string{"inti", "new"},
 	PreRunE:    bindEnv("runtime", "templates", "trigger", "confirm"),

Diff for: cmd/delete.go

@@ -13,25 +13,28 @@ import (
 
 func init() {
 	root.AddCommand(deleteCmd)
-	deleteCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FUNC_CONFIRM")
-	deleteCmd.Flags().StringP("path", "p", cwd(), "Path to the project which should be deleted - $FUNC_PATH")
-	deleteCmd.Flags().StringP("namespace", "n", "", "Override namespace in which to search for Functions.  Default is to use currently active underlying platform setting - $FAAS_NAMESPACE")
+	deleteCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)")
+	deleteCmd.Flags().StringP("path", "p", cwd(), "Path to the function project that should be undeployed (Env: $FUNC_PATH)")
+	deleteCmd.Flags().StringP("namespace", "n", "", "Namespace of the function to undeploy. By default, the namespace in func.yaml is used or the actual active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)")
 }
 
 var deleteCmd = &cobra.Command{
-	Use:   "delete <name>",
-	Short: "Delete a Function deployment",
-	Long: `Delete a Function deployment
-
-Removes a deployed function from the cluster. The user may specify a function
-by name, path using the --path or -p flag, or if neither of those are provided,
-the current directory will be searched for a func.yaml configuration file to
-determine the function to be removed.
-
-The namespace defaults to the value in func.yaml or the namespace currently
-active in the user's Kubernetes configuration. The namespace may be specified
-on the command line using the --namespace or -n flag, and if so this will
-overwrite the value in func.yaml.
+	Use:   "delete [NAME]",
+	Short: "Undeploy a function",
+	Long: `Undeploy a function
+
+This command undeploys a function from the cluster. By default the function from 
+the project in the current directory is undeployed. Alternatively either the name 
+of the function can be given as argument or the project path provided with --path.
+
+No local files are deleted.
+`,
+	Example: `
+# Undeploy the function defined in the local directory
+kn func delete
+
+# Undeploy the function 'myfunc' in namespace 'apps'
+kn func delete -n apps myfunc
 `,
 	SuggestFor:        []string{"remove", "rm", "del"},
 	ValidArgsFunction: CompleteFunctionList,
@@ -49,7 +52,7 @@ func runDelete(cmd *cobra.Command, args []string) (err error) {
 
 	// Check if the Function has been initialized
 	if !function.Initialized() {
-		return fmt.Errorf("the given path '%v' does not contain an initialized Function.", config.Path)
+		return fmt.Errorf("the given path '%v' does not contain an initialized function", config.Path)
 	}
 
 	ns := config.Namespace

Diff for: cmd/deploy.go

@@ -15,37 +15,39 @@ import (
 
 func init() {
 	root.AddCommand(deployCmd)
-	deployCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FUNC_CONFIRM")
-	deployCmd.Flags().StringArrayP("env", "e", []string{}, "Sets environment variables for the Function.")
-	deployCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --registry) - $FUNC_IMAGE")
-	deployCmd.Flags().StringP("namespace", "n", "", "Override namespace into which the Function is deployed (on supported platforms).  Default is to use currently active underlying platform setting - $FUNC_NAMESPACE")
-	deployCmd.Flags().StringP("path", "p", cwd(), "Path to the function project directory - $FUNC_PATH")
-	deployCmd.Flags().StringP("registry", "r", "", "Image registry for built images, ex 'docker.io/myuser' or just 'myuser'.  - $FUNC_REGISTRY")
+	deployCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)")
+	deployCmd.Flags().StringArrayP("env", "e", []string{}, "Environment variable to set in the form NAME=VALUE. You may provide this flag multiple times for setting multiple environment variables.")
+	deployCmd.Flags().StringP("image", "i", "", "Full image name in the orm [registry]/[namespace]/[name]:[tag] (optional). This option takes precedence over --registry (Env: $FUNC_IMAGE")
+	deployCmd.Flags().StringP("namespace", "n", "", "Namespace of the function to undeploy. By default, the namespace in func.yaml is used or the actual active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)")
+	deployCmd.Flags().StringP("path", "p", cwd(), "Path to the project directory (Env: $FUNC_PATH)")
+	deployCmd.Flags().StringP("registry", "r", "", "Registry + namespace part of the image to build, ex 'quay.io/myuser'.  The full image name is automatically determined based on the local directory name. If not provided the registry will be taken from func.yaml (Env: $FUNC_REGISTRY)")
 }
 
 var deployCmd = &cobra.Command{
 	Use:   "deploy",
-	Short: "Deploy an existing Function project to a cluster",
-	Long: `Deploy an existing Function project to a cluster
-
-Builds and Deploys the Function project in the current directory. 
-A path to the project directory may be provided using the --path or -p flag.
-Reads the func.yaml configuration file to determine the image name. 
-An image and registry may be specified on the command line using 
-the --image or -i and --registry or -r flag.
-
-If the Function is already deployed, it is updated with a new container image
-that is pushed to an image registry, and the Knative Service is updated.
-
-The namespace into which the project is deployed defaults to the value in the
-func.yaml configuration file. If NAMESPACE is not set in the configuration,
-the namespace currently active in the Kubernetes configuration file will be
-used. The namespace may be specified on the command line using the --namespace
-or -n flag, and if so this will overwrite the value in the func.yaml file.
+	Short: "Deploy a function",
+	Long: `Deploy a function
 
+Builds a container image for the function and deploys it to the connected Knative enabled cluster. 
+The function is picked up from the project in the current directory or from the path provided
+with --path.
+If not already configured, either --registry or --image has to be provided and is then stored 
+in the configuration file.
 
+If the function is already deployed, it is updated with a new container image
+that is pushed to an image registry, and finally the function's Knative service is updated.
+`,
+	Example: `
+# Build and deploy the function from the current directory's project. The image will be
+# pushed to "quay.io/myuser/<function name>" and deployed as Knative service with the 
+# same name as the function to the currently connected cluster.
+kn func deploy --registry quay.io/myuser
+
+# Same as above but using a full image name, that will create a Knative service "myfunc" in 
+# the namespace "myns"
+kn func deploy --image quay.io/myuser/myfunc -n myns
 `,
-	SuggestFor: []string{"delpoy", "deplyo"},
+    SuggestFor: []string{"delpoy", "deplyo"},
 	PreRunE:    bindEnv("image", "namespace", "path", "registry", "confirm"),
 	RunE:       runDeploy,
 }
@@ -63,7 +65,7 @@ func runDeploy(cmd *cobra.Command, _ []string) (err error) {
 
 	// Check if the Function has been initialized
 	if !function.Initialized() {
-		return fmt.Errorf("the given path '%v' does not contain an initialized Function. Please create one at this path before deploying.", config.Path)
+		return fmt.Errorf("the given path '%v' does not contain an initialized function. Please create one at this path before deploying", config.Path)
 	}
 
 	// If the Function does not yet have an image name and one was not provided on the command line
@@ -74,7 +76,7 @@ func runDeploy(cmd *cobra.Command, _ []string) (err error) {
 			fmt.Print("A registry for Function images is required. For example, 'docker.io/tigerteam'.\n\n")
 			config.Registry = prompt.ForString("Registry for Function images", "")
 			if config.Registry == "" {
-				return fmt.Errorf("Unable to determine Function image name")
+				return fmt.Errorf("unable to determine function image name")
 			}
 		}
 

Diff for: cmd/describe.go

@@ -17,28 +17,30 @@ import (
 
 func init() {
 	root.AddCommand(describeCmd)
-	describeCmd.Flags().StringP("namespace", "n", "", "Override namespace in which to search for the Function.  Default is to use currently active underlying platform setting - $FUNC_NAMESPACE")
-	describeCmd.Flags().StringP("format", "f", "human", "optionally specify output format (human|plain|json|xml|yaml) $FUNC_FORMAT")
-	describeCmd.Flags().StringP("path", "p", cwd(), "Path to the project which should be described - $FUNC_PATH")
+	describeCmd.Flags().StringP("namespace", "n", "", "Namespace of the function to undeploy. By default, the namespace in func.yaml is used or the actual active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)")
+	describeCmd.Flags().StringP("format", "f", "human", "Output format (human|plain|json|xml|yaml) (Env: $FUNC_FORMAT)")
+	describeCmd.Flags().StringP("path", "p", cwd(), "Path to the project directory (Env: $FUNC_PATH)")
 
 	err := describeCmd.RegisterFlagCompletionFunc("format", CompleteOutputFormatList)
 	if err != nil {
-		fmt.Println("Error while calling RegisterFlagCompletionFunc: ", err)
+		fmt.Println("internal: error while calling RegisterFlagCompletionFunc: ", err)
 	}
 }
 
 var describeCmd = &cobra.Command{
 	Use:   "describe <name>",
-	Short: "Describes the Function",
-	Long: `Describes the Function
+	Short: "Show details of a function",
+	Long: `Show details of a function
 
-Prints the name, route and any event subscriptions for a deployed Function in
-the current directory. A path to a Function project directory may be supplied
-using the --path or -p flag.
+Prints the name, route and any event subscriptions for a deployed function in
+the current directory or from the directory specified with --path.
+`,
+    Example: `
+# Show the details of a function as declared in the local func.yaml
+kn func describe
 
-The namespace defaults to the value in func.yaml or the namespace currently
-active in the user's Kubernetes configuration. The namespace may be specified
-using the --namespace or -n flag, and if so this will overwrite the value in func.yaml.
+# Show the details of the function in YAML format for the function in the myotherfunc directory
+kn func describe --format yaml --path myotherfunc
 `,
 	SuggestFor:        []string{"desc", "get"},
 	ValidArgsFunction: CompleteFunctionList,
@@ -56,7 +58,7 @@ func runDescribe(cmd *cobra.Command, args []string) (err error) {
 
 	// Check if the Function has been initialized
 	if !function.Initialized() {
-		return fmt.Errorf("the given path '%v' does not contain an initialized Function.", config.Path)
+		return fmt.Errorf("the given path '%v' does not contain an initialized function", config.Path)
 	}
 
 	describer, err := knative.NewDescriber(config.Namespace)