Added comments for exported functions and regenerated docs

docs/cmd/kn_broker_create.md

@@ -16,14 +16,26 @@ kn broker create NAME
   # Create a broker 'mybroker' in the 'myproject' namespace and with a broker class of 'Kafka'
   kn broker create mybroker --namespace myproject --class Kafka
 
+  # Create a broker 'mybroker' in the myproject namespace with config referencing configmap named spec-cm
+  kn broker create mybroker --namespace myproject --class Kafka --broker-config cm:spec-cm
+
+  # Create a broker 'mybroker' in the myproject namespace with config referencing configmap named spec-cm in test namespace
+  kn broker create mybroker --namespace myproject --class Kafka --broker-config cm:broker-spec-cm:test
+
+  # Create a broker 'mybroker' in the myproject namespace with config referencing configmap named spec-cm in test namespace
+  kn broker create mybroker --namespace myproject --class Kafka --broker-config cm:broker-spec-cm:test
+
 ```
 
 ### Options
 
 ```
       --backoff-delay string     The delay before retrying.
       --backoff-policy string    The retry backoff policy (linear, exponential).
-      --broker-config string     Broker config object like ConfigMap or RabbitMQ
+      --broker-config string     Reference to the configuration that specifies configuration options for this Broker. For example, a pointer to a ConfigMap, Secret, RabbitmqCluster etc.The format for specifying the object is a colon separated string consisting of at most 3 substrings:
+                                 kind:object-name:namespace=?,apiVersion=?,group=?
+                                 The third substring is optional and the following is also acceptable (in case of ConfigMap, Secret, and RabbitmqCluster kinds):
+                                 kind:object-name
       --class string             Broker class like 'MTChannelBasedBroker' or 'Kafka' (if available).
       --dl-sink string           The sink receiving event that could not be sent to a destination.
   -h, --help                     help for create

pkg/kn/commands/broker/config_flags.go

@@ -33,21 +33,32 @@ const (
 )
 
 var (
+	// KReferenceMapping is mapping between the known config kinds to a basic
+	// default KReference value
 	KReferenceMapping = map[ConfigType]*duckv1.KReference{
 		ConfigMapType: {Kind: "ConfigMap", APIVersion: "v1"},
 		SecretType:    {Kind: "Secret", APIVersion: "v1"},
 		RabbitMqType:  {Kind: "RabbitmqCluster", APIVersion: "rabbitmq.com/v1beta1"},
 	}
 )
 
+// ConfigFlags represents the broker config
 type ConfigFlags struct {
 	BrokerConfig string
 }
 
+// Add is used to add the broker config flag to a command
 func (c *ConfigFlags) Add(cmd *cobra.Command) {
-	cmd.Flags().StringVar(&c.BrokerConfig, "broker-config", "", "Broker config object like ConfigMap or RabbitMQ")
+	cmd.Flags().StringVar(&c.BrokerConfig, "broker-config", "", "Reference to the configuration "+
+		"that specifies configuration options for this Broker. For example, a pointer to a ConfigMap, Secret, RabbitmqCluster etc."+
+		"The format for specifying the object is a colon separated string consisting of at most 3 substrings:\n"+
+		"kind:object-name:namespace=?,apiVersion=?,group=?\nThe third substring is optional and the following is also acceptable "+
+		"(in case of ConfigMap, Secret, and RabbitmqCluster kinds):\n"+
+		"kind:object-name")
 }
 
+// GetBrokerConfigReference parses the broker config
+// and return the appropriate KReference object
 func (c *ConfigFlags) GetBrokerConfigReference() (*duckv1.KReference, error) {
 	config := c.BrokerConfig
 	slices := strings.SplitN(config, ":", 3)

pkg/kn/commands/broker/create.go

@@ -34,6 +34,15 @@ var createExample = `
 
   # Create a broker 'mybroker' in the 'myproject' namespace and with a broker class of 'Kafka'
   kn broker create mybroker --namespace myproject --class Kafka
+
+  # Create a broker 'mybroker' in the myproject namespace with config referencing configmap named spec-cm
+  kn broker create mybroker --namespace myproject --class Kafka --broker-config cm:spec-cm
+
+  # Create a broker 'mybroker' in the myproject namespace with config referencing configmap named spec-cm in test namespace
+  kn broker create mybroker --namespace myproject --class Kafka --broker-config cm:broker-spec-cm:test
+
+  # Create a broker 'mybroker' in the myproject namespace with config referencing configmap named spec-cm in test namespace
+  kn broker create mybroker --namespace myproject --class Kafka --broker-config cm:broker-spec-cm:test
 `
 
 // NewBrokerCreateCommand represents command to create new broker instance