improve apply and config command help (#1194)

cmd/registry/cmd/apply/apply.go

@@ -33,10 +33,12 @@ func Command() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "apply (-f FILE | -f -)",
 		Short: "Apply YAML to the API Registry",
-		Long: "Apply YAML to the API Registry by files / folder names or stdin. " +
-			"Resources will be created if they don't exist yet. " +
-			"Multiple files may be specified by repeating the -f flag." +
-			"\n\nMore info and example usage at https://github.com/apigee/registry/wiki/registry-apply",
+		Long: `Apply YAML to the API Registry by files / folder names or stdin.
+
+Resources will be created if they don't exist yet. 
+Multiple files may be specified by repeating the -f flag.
+
+More info and example usage at https://github.com/apigee/registry/wiki/registry-apply.`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(files) > 1 {

cmd/registry/cmd/auth/auth.go

@@ -24,14 +24,21 @@ import (
 func Command() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "auth",
-		Short: "Manage authentication to the API Registry",
-		Long: "Authentication to the registry is via tokens. These tokens can be provided " +
-			"directly by using '--registry.token' in any command, or can be generated as needed " +
-			"by setting the token-source property in a configuration. The token-source can be set " +
-			"to any executable command that prints a registry token by using the 'config set token-source'. " +
-			"Once set, the command will be executed before a registry command is run and the output used " +
-			"as the token passed to the registry. The output can be verified by 'auth print-token'.",
-		Example: "config set token-source 'gcloud auth print-access-token [email protected]'",
+		Short: "Manage client authentication to the API Registry",
+		Long: `Manage client authentication to the API Registry.
+		
+Authentication to the registry is via tokens. These tokens can be provided
+directly by using '--registry.token' in any command, or can be generated as 
+needed by setting the token-source property in a configuration. 
+
+The token-source can be set to any executable command that prints a registry 
+token by using 'registry config set token-source'. Once set, the command will
+be executed before a registry command is run and the output used as the token
+passed to the registry. 
+
+Output of the token-source setting can be verified by 'auth print-token'.`,
+		Example: `registry config set token-source 'gcloud auth print-access-token [email protected]
+registry auth print-token`,
 	}
 
 	cmd.AddCommand(printTokenCommand())

cmd/registry/cmd/config/config.go

@@ -23,10 +23,21 @@ func Command() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config",
 		Short: "Maintain properties in the active configuration",
-		Long: "Configurations manage sets of properties used when connecting to the registry. " +
-			"These commands manipulate the property values in the active configuration. " +
-			"See `config configurations --help` for information on how to manage configurations. " +
-			"See `config set --help` for the list of properties available.",
+		Long: `Maintain properties in the active configuration.
+		
+Configurations manage sets of properties used when a client connects to the 
+API Registry. These commands display manipulate the property values in the 
+active configuration.
+
+The following are valid configuration properties:
+	- address
+	- insecure
+	- location
+	- project
+	- token-source
+
+See 'config configurations --help' for information on how to manage configurations.
+See 'config set --help' for the list of properties available.`,
 	}
 
 	cmd.AddCommand(configurations.Command())

cmd/registry/cmd/config/configurations/activate.go

@@ -23,9 +23,10 @@ import (
 
 func activateCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "activate CONFIGURATION",
-		Short: "Activates an existing named configuration",
-		Args:  cobra.ExactArgs(1),
+		Use:     "activate CONFIGURATION",
+		Short:   "Activates an existing named configuration",
+		Example: `registry config configurations activate local`,
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			name := args[0]
 			if err := config.ValidateName(name); err != nil {

cmd/registry/cmd/config/configurations/configurations.go

@@ -22,11 +22,17 @@ func Command() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "configurations",
 		Short: "Maintain named configurations of properties",
-		Long: "Configurations manage sets of properties used when connecting to the registry. " +
-			"These commands manipulate named sets of these properties, called 'configurations'. " +
-			"When a configuration is 'active', it's properties are automatically loaded and used " +
-			"by registry commands. See `registry config` for manipulating the properties themselves. " +
-			"Configuration files are stored in the $HOME/.config/registry folder.",
+		Long: `Maintain named configurations of properties.
+		
+Configurations are sets of properties used by a client when connecting to
+the API Registry. These commands manipulate these named sets of properties
+stored in the '$HOME/.config/registry folder.
+
+When a configuration is 'active', its properties are automatically loaded 
+and used, although they can be overridden by flags and environment variables.
+
+See 'registry config' for commands to manipulate the properties within a
+configuration.`,
 	}
 
 	cmd.AddCommand(activateCommand())

cmd/registry/cmd/config/configurations/create.go

@@ -30,10 +30,13 @@ func createCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create CONFIGURATION",
 		Short: "Creates and activates a new named configuration",
-		Long: "Creates and activates a new named configuration. Values will be populated from active " +
-			"configuration (if any) and any passed property flags (unless using --gcloud).",
-		Example: "registry config configurations create localhost --registry.address='locahost:8080'\n" +
-			"registry config configurations create hosted --gcloud",
+		Long: `Creates and activates a new named configuration. 
+		
+Values in the new configuration will default to the currently active
+configuration (if any) but can be overridden by setting property flags
+(unless using --gcloud).`,
+		Example: `registry config configurations create localhost --registry.address='locahost:8080'
+registry config configurations create hosted --gcloud`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			name := args[0]

cmd/registry/cmd/config/configurations/delete.go

@@ -24,9 +24,10 @@ import (
 
 func deleteCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "delete CONFIGURATION_1 ... CONFIGURATION_N",
-		Short: "Deletes a named configuration",
-		Args:  cobra.MinimumNArgs(1),
+		Use:     "delete CONFIGURATION_1 ... CONFIGURATION_N",
+		Short:   "Deletes a named configuration",
+		Example: `registry config configurations delete local`,
+		Args:    cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			for _, name := range args {
 				if err := config.ValidateName(name); err != nil {

cmd/registry/cmd/config/configurations/describe.go

@@ -24,9 +24,10 @@ import (
 
 func describeCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "describe CONFIGURATION",
-		Short: "Describes a named configuration by listing its properties",
-		Args:  cobra.ExactArgs(1),
+		Use:     "describe CONFIGURATION",
+		Short:   "Describes a named configuration by listing its properties",
+		Example: `registry config configurations describe localhost`,
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			name := args[0]
 			s, err := config.Read(name)

cmd/registry/cmd/config/configurations/list.go

@@ -27,9 +27,10 @@ import (
 
 func listCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "list",
-		Short: "Lists existing named configs",
-		Args:  cobra.NoArgs,
+		Use:     "list",
+		Short:   "Lists existing named configurations",
+		Example: `registry config configurations list`,
+		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			configs, err := config.Configurations()
 			if errors.Is(err, fs.ErrNotExist) || len(configs) == 0 {

cmd/registry/cmd/config/get.go

@@ -23,9 +23,18 @@ import (
 
 func getCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "get PROPERTY",
-		Short: "Print a property value in the active configuration",
-		Args:  cobra.ExactArgs(1),
+		Use:     "get PROPERTY",
+		Short:   "Print a property value in the active configuration",
+		Example: `registry config get address`,
+		Long: `Print a property value in the active configuration.
+
+The following are valid configuration properties:
+	- address
+	- insecure
+	- location
+	- project
+	- token-source`,
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			_, c, err := config.ActiveRaw()
 			if err != nil {

cmd/registry/cmd/config/list.go

@@ -23,9 +23,10 @@ import (
 
 func listCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "list",
-		Short: "List properties in the active configuration",
-		Args:  cobra.NoArgs,
+		Use:     "list",
+		Short:   "List properties in the active configuration",
+		Example: `registry config list`,
+		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			target, c, err := config.ActiveRaw()
 			if err != nil {

cmd/registry/cmd/config/set.go

@@ -25,14 +25,16 @@ func setCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "set PROPERTY VALUE",
 		Short: "Set a property value in the active configuration",
-		Long: "Set a property value in the active configuration. The following are valid properties:\n" +
-			"  - registry.address\n" +
-			"  - registry.insecure\n" +
-			"  - registry.location\n" +
-			"  - registry.project\n" +
-			"  - token-source",
-		Example: "registry config set registry.address localhost:8080\n" +
-			"registry config set token-source 'gcloud auth print-access-token [email protected]'",
+		Long: `Set a property value in the active configuration.
+
+The following are valid configuration properties:
+	- address
+	- insecure
+	- location
+	- project
+	- token-source`,
+		Example: `registry config set address localhost:8080
+registry config set token-source 'gcloud auth print-access-token [email protected]'`,
 		Args: cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			target, c, err := config.ActiveRaw()