docs(api): cleans up property descriptions

api/src/main/java/io/strimzi/api/kafka/model/bridge/KafkaBridgeConsumerSpec.java

@@ -41,7 +41,8 @@ public Map<String, Object> getConfig() {
     }
 
     @JsonInclude(JsonInclude.Include.NON_DEFAULT)
-    @Description("Whether the HTTP consumer should be enabled or disabled, default is enabled.")
+    @Description("Whether the HTTP consumer should be enabled or disabled. " +
+        "The default is enabled (`true`).")
     public boolean isEnabled() {
         return enabled;
     }

api/src/main/java/io/strimzi/api/kafka/model/bridge/KafkaBridgeProducerSpec.java

@@ -38,7 +38,8 @@ public Map<String, Object> getConfig() {
     }
 
     @JsonInclude(JsonInclude.Include.NON_DEFAULT)
-    @Description("Whether the HTTP producer should be enabled or disabled, default is enabled.")
+    @Description("Whether the HTTP producer should be enabled or disabled. " +
+        "The default is enabled (`true`).")
     public boolean isEnabled() {
         return enabled;
     }

api/src/main/java/io/strimzi/api/kafka/model/kafka/KafkaClusterSpec.java

@@ -254,7 +254,7 @@ public void setMetricsConfig(MetricsConfig metricsConfig) {
         this.metricsConfig = metricsConfig;
     }
 
-    @Description("Configures listeners of Kafka brokers")
+    @Description("Configures listeners to provide access to Kafka brokers.")
     @MinimumItems(1)
     @JsonProperty(required = true)
     public List<GenericKafkaListener> getListeners() {

api/src/main/java/io/strimzi/api/kafka/model/kafka/listener/GenericKafkaListener.java

@@ -105,7 +105,8 @@ public void setAuth(KafkaListenerAuthentication auth) {
     }
 
     @Description("Enables TLS encryption on the listener. " +
-            "This is a required property.")
+            "This is a required property. " + 
+            "For `route` and `ingress` type listeners, TLS encryption must be always enabled.")
     @JsonProperty(required = true)
     public boolean isTls() {
         return tls;

api/src/main/java/io/strimzi/api/kafka/model/kafka/listener/GenericKafkaListenerConfiguration.java

@@ -67,11 +67,12 @@ public void setBrokerCertChainAndKey(CertAndKeySecretSource brokerCertChainAndKe
         this.brokerCertChainAndKey = brokerCertChainAndKey;
     }
 
-    @Description("Configures a specific class for `Ingress` and `LoadBalancer` that defines which controller will be used. " +
-            "This field can only be used with `ingress` and `loadbalancer` type listeners. " +
-            "If not specified, the default controller is used. " +
-            "For an `ingress` listener, set the `ingressClassName` property in the `Ingress` resources. " +
-            "For a `loadbalancer` listener, set the `loadBalancerClass` property  in the `Service` resources.")
+    @Description("Configures a specific class for `Ingress` and `LoadBalancer` that defines which controller is used. " +
+            "If not specified, the default controller is used.\n\n" +
+            "* For an `ingress` listener, the operator uses this property to set the `ingressClassName` property in the `Ingress` resources.\n" +
+            "* For a `loadbalancer` listener, the operator uses this property to set the `loadBalancerClass` property  in the `Service` resources.\n" +
+            "\n" +
+            "For `ingress` and `loadbalancer` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     @JsonProperty("class")
     public String getControllerClass() {
@@ -84,16 +85,16 @@ public void setControllerClass(String controllerClass) {
 
     @Description("Defines which address type should be used as the node address. " +
             "Available types are: `ExternalDNS`, `ExternalIP`, `InternalDNS`, `InternalIP` and `Hostname`. " +
-            "By default, the addresses will be used in the following order (the first one found will be used):\n\n" +
+            "By default, the addresses are used in the following order (the first one found is used):\n\n" +
             "* `ExternalDNS`\n" +
             "* `ExternalIP`\n" +
             "* `InternalDNS`\n" +
             "* `InternalIP`\n" +
             "* `Hostname`\n" +
             "\n" +
-            "This field is used to select the preferred address type, which is checked first. " +
-            "If no address is found for this address type, the other types are checked in the default order. " +
-            "This field can only be used with `nodeport` type listener.")
+            "This property is used to select the preferred address type, which is checked first. " +
+            "If no address is found for this address type, the other types are checked in the default order." +
+            "For `nodeport` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public NodeAddressType getPreferredNodePortAddressType() {
         return preferredNodePortAddressType;
@@ -103,11 +104,12 @@ public void setPreferredNodePortAddressType(NodeAddressType preferredNodePortAdd
         this.preferredNodePortAddressType = preferredNodePortAddressType;
     }
 
-    @Description("Specifies whether the service routes external traffic to node-local or cluster-wide endpoints. " +
-            "`Cluster` may cause a second hop to another node and obscures the client source IP. " +
-            "`Local` avoids a second hop for LoadBalancer and Nodeport type services and preserves the client source IP (when supported by the infrastructure). " +
-            "If unspecified, Kubernetes will use `Cluster` as the default." +
-            "This field can be used only with `loadbalancer` or `nodeport` type listener.")
+    @Description("Specifies whether the service routes external traffic to cluster-wide or node-local endpoints:\n\n" +
+            "* `Cluster` may cause a second hop to another node and obscures the client source IP.\n" +
+            "* `Local` avoids a second hop for `LoadBalancer` and `Nodeport` type services and preserves the client source IP (when supported by the infrastructure).\n" +
+            "\n" +
+            "If unspecified, Kubernetes uses `Cluster` as the default. " +
+            "For `loadbalancer` or `nodeport` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public ExternalTrafficPolicy getExternalTrafficPolicy() {
         return externalTrafficPolicy;
@@ -117,10 +119,10 @@ public void setExternalTrafficPolicy(ExternalTrafficPolicy externalTrafficPolicy
         this.externalTrafficPolicy = externalTrafficPolicy;
     }
 
-    @Description("A list of CIDR ranges (for example `10.0.0.0/8` or `130.211.204.1/32`) from which clients can connect to load balancer type listeners. " +
+    @Description("A list of CIDR ranges (for example `10.0.0.0/8` or `130.211.204.1/32`) from which clients can connect to loadbalancer listeners. " +
             "If supported by the platform, traffic through the loadbalancer is restricted to the specified CIDR ranges. " +
             "This field is applicable only for loadbalancer type services and is ignored if the cloud provider does not support the feature. " +
-            "This field can be used only with `loadbalancer` type listener.")
+            "For `loadbalancer` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public List<String> getLoadBalancerSourceRanges() {
         return loadBalancerSourceRanges;
@@ -130,10 +132,10 @@ public void setLoadBalancerSourceRanges(List<String> loadBalancerSourceRanges) {
         this.loadBalancerSourceRanges = loadBalancerSourceRanges;
     }
 
-    @Description("A list of finalizers which will be configured for the `LoadBalancer` type Services created for this listener. " +
+    @Description("A list of finalizers configured for the `LoadBalancer` type services created for this listener. " +
             "If supported by the platform, the finalizer `service.kubernetes.io/load-balancer-cleanup` to make sure that the external load balancer is deleted together with the service." +
             "For more information, see https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#garbage-collecting-load-balancers. " +
-            "This field can be used only with `loadbalancer` type listeners.")
+            "For `loadbalancer` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public List<String> getFinalizers() {
         return finalizers;
@@ -143,11 +145,14 @@ public void setFinalizers(List<String> finalizers) {
         this.finalizers = finalizers;
     }
 
-    @Description("Configures whether the Kubernetes service DNS domain should be used or not. " +
-            "If set to `true`, the generated addresses will contain the service DNS domain suffix " +
-            "(by default `.cluster.local`, can be configured using environment variable `KUBERNETES_SERVICE_DNS_DOMAIN`). " +
-            "Defaults to `false`." +
-            "This field can be used only with `internal` and `cluster-ip` type listeners.")
+    @Description("Configures whether the Kubernetes service DNS domain should be included in the generated addresses.\n\n" +
+            "* If set to `false`, the generated addresses do not contain the service DNS domain suffix. " +
+            "For example, `my-cluster-kafka-0.my-cluster-kafka-brokers.myproject.svc`.\n" +
+            "* If set to `true`, the generated addresses contain the service DNS domain suffix. " +
+            "For example, `my-cluster-kafka-0.my-cluster-kafka-brokers.myproject.svc.cluster.local`.\n" +
+            "\n" +
+            "The default is `.cluster.local`, but this is customizable using the environment variable `KUBERNETES_SERVICE_DNS_DOMAIN`. " +
+            "For `internal` and `cluster-ip` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public Boolean getUseServiceDnsDomain() {
         return useServiceDnsDomain;
@@ -198,10 +203,11 @@ public void setMaxConnectionCreationRate(Integer maxConnectionCreationRate) {
     }
 
     @Description("Specifies the IP Family Policy used by the service. " +
-            "Available options are `SingleStack`, `PreferDualStack` and `RequireDualStack`. " +
-            "`SingleStack` is for a single IP family. " +
-            "`PreferDualStack` is for two IP families on dual-stack configured clusters or a single IP family on single-stack clusters. " +
-            "`RequireDualStack` fails unless there are two IP families on dual-stack configured clusters. " +
+            "Available options are `SingleStack`, `PreferDualStack` and `RequireDualStack`:\n\n" +
+            "* `SingleStack` is for a single IP family.\n" +
+            "* `PreferDualStack` is for two IP families on dual-stack configured clusters or a single IP family on single-stack clusters.\n" +
+            "* `RequireDualStack` fails unless there are two IP families on dual-stack configured clusters.\n" +
+            "\n" +
             "If unspecified, Kubernetes will choose the default value based on the service type.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     @PresentInVersions("v1beta2+")
@@ -228,7 +234,7 @@ public void setIpFamilies(List<IpFamily> ipFamilies) {
 
     @Description("Whether to create the bootstrap service or not. " +
             "The bootstrap service is created by default (if not specified differently). " +
-            "This field can be used with the `loadBalancer` type listener.")
+            "This field can be used with the `loadbalancer` listener.")
     @JsonInclude(JsonInclude.Include.NON_DEFAULT)
     public Boolean getCreateBootstrapService() {
         return createBootstrapService;
@@ -240,7 +246,7 @@ public void setCreateBootstrapService(Boolean createBootstrapService) {
 
     @Description("Configures whether the service endpoints are considered \"ready\" even if the Pods themselves are not. " +
             "Defaults to `false`. " +
-            "This field can not be used with `internal` type listeners.")
+            "This field can not be used with `internal` listeners.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public Boolean getPublishNotReadyAddresses() {
         return publishNotReadyAddresses;

api/src/main/java/io/strimzi/api/kafka/model/kafka/listener/GenericKafkaListenerConfigurationBootstrap.java

@@ -52,9 +52,9 @@ public void setAlternativeNames(List<String> alternativeNames) {
         this.alternativeNames = alternativeNames;
     }
 
-    @Description("The bootstrap host. " +
-            "This field will be used in the Ingress resource or in the Route resource to specify the desired hostname. " +
-            "This field can be used only with `route` (optional) or `ingress` (required) type listeners.")
+    @Description("Specifies the hostname used for the bootstrap resource. " +
+        "For `route` (optional) or `ingress` (required) listeners only. " +
+        "Ensure the hostname resolves to the Ingress endpoints; no validation is performed by Strimzi.") 
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public String getHost() {
         return host;
@@ -64,9 +64,9 @@ public void setHost(String host) {
         this.host = host;
     }
 
-    @Description("Annotations that will be added to the `Ingress`, `Route`, or `Service` resource. " +
-            "You can use this field to configure DNS providers such as External DNS. " +
-            "This field can be used only with `loadbalancer`, `nodeport`, `route`, or `ingress` type listeners.")
+    @Description("Annotations added to `Ingress`, `Route`, or `Service` resources. " +
+            "You can use this property to configure DNS providers such as External DNS. " +
+            "For `loadbalancer`, `nodeport`, `route`, or `ingress` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public Map<String, String> getAnnotations() {
         return annotations;
@@ -76,8 +76,8 @@ public void setAnnotations(Map<String, String> annotations) {
         this.annotations = annotations;
     }
 
-    @Description("Labels that will be added to the `Ingress`, `Route`, or `Service` resource. " +
-            "This field can be used only with `loadbalancer`, `nodeport`, `route`, or `ingress` type listeners.")
+    @Description("Labels added to `Ingress`, `Route`, or `Service` resources. " +
+            "For `loadbalancer`, `nodeport`, `route`, or `ingress` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public Map<String, String> getLabels() {
         return labels;
@@ -88,7 +88,7 @@ public void setLabels(Map<String, String> labels) {
     }
 
     @Description("Node port for the bootstrap service. " +
-            "This field can be used only with `nodeport` type listener.")
+            "For `nodeport` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public Integer getNodePort() {
         return nodePort;
@@ -98,10 +98,10 @@ public void setNodePort(Integer nodePort) {
         this.nodePort = nodePort;
     }
 
-    @Description("The loadbalancer is requested with the IP address specified in this field. " +
+    @Description("The loadbalancer is requested with the IP address specified in this property. " +
             "This feature depends on whether the underlying cloud provider supports specifying the `loadBalancerIP` when a load balancer is created. " +
-            "This field is ignored if the cloud provider does not support the feature." +
-            "This field can be used only with `loadbalancer` type listener.")
+            "This property is ignored if the cloud provider does not support the feature. " +
+            "For `loadbalancer` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public String getLoadBalancerIP() {
         return loadBalancerIP;
@@ -113,8 +113,8 @@ public void setLoadBalancerIP(String loadBalancerIP) {
 
     @Description("External IPs associated to the nodeport service. " + 
             "These IPs are used by clients external to the Kubernetes cluster to access the Kafka brokers. " +
-            "This field is helpful when `nodeport` without `externalIP` is not sufficient. For example on bare-metal Kubernetes clusters that do not support Loadbalancer service types. " +
-            "This field can only be used with `nodeport` type listener.")
+            "This property is helpful when `nodeport` without `externalIP` is not sufficient. For example on bare-metal Kubernetes clusters that do not support Loadbalancer service types. " +
+            "For `nodeport` listeners only.")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public List<String> getExternalIPs() {
         return externalIPs;

api/src/main/java/io/strimzi/api/kafka/model/kafka/listener/KafkaListenerAuthenticationCustom.java

@@ -55,7 +55,7 @@ public void setSasl(boolean enabled) {
         this.sasl = enabled;
     }
 
-    @Description("Configuration to be used for a specific listener. All values are prefixed with listener.name._<listener_name>_.")
+    @Description("Configuration to be used for a specific listener. All values are prefixed with `listener.name.<listener_name>`.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public Map<String, Object> getListenerConfig() {
         return listenerConfig;
@@ -65,7 +65,7 @@ public void setListenerConfig(Map<String, Object> config) {
         this.listenerConfig = config;
     }
 
-    @Description("Secrets to be mounted to /opt/kafka/custom-authn-secrets/custom-listener-_<listener_name>-<port>_/_<secret_name>_")
+    @Description("Secrets to be mounted to `/opt/kafka/custom-authn-secrets/custom-listener-<listener_name>-<port>/<secret_name>`")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public List<GenericSecretSource> getSecrets() {
         return secrets;

api/src/main/java/io/strimzi/api/kafka/model/user/acl/AclRule.java

@@ -99,8 +99,9 @@ public void setOperation(AclOperation operation) {
         this.operation = operation;
     }
 
-    @Description("List of operations which will be allowed or denied. " +
-            "Supported operations are: Read, Write, Create, Delete, Alter, Describe, ClusterAction, AlterConfigs, DescribeConfigs, IdempotentWrite and All.")
+    @Description("List of operations to allow or deny. " +
+            "Supported operations are: Read, Write, Create, Delete, Alter, Describe, ClusterAction, AlterConfigs, DescribeConfigs, IdempotentWrite and All. " +
+            "Only certain operations work with the specified resource.")
     @Example("operations: [\"Read\",\"Write\"]")
     public List<AclOperation> getOperations() {
         return operations;

documentation/api/io.strimzi.api.kafka.model.bridge.KafkaBridgeConsumerSpec.adoc

@@ -1,4 +1,24 @@
-Configures consumer options for the Kafka Bridge as keys.
+Configures consumer options for the Kafka Bridge.
+
+.Example Kafka Bridge consumer configuration
+[source,yaml,subs="attributes+"]
+----
+apiVersion: {KafkaBridgeApiVersion}
+kind: KafkaBridge
+metadata:
+  name: my-bridge
+spec:
+  # ...
+  consumer:
+    enabled: true
+    timeoutSeconds: 60
+    config:
+      auto.offset.reset: earliest
+      enable.auto.commit: true
+    # ...
+----
+
+Use the `consumer.config` properties to configure Kafka options for the consumer as keys.
 
 The values can be one of the following JSON types:
 
@@ -29,34 +49,6 @@ All other supported options are forwarded to Kafka Bridge, including the followi
 
 * Any `ssl` configuration for xref:con-common-configuration-ssl-reference[supported TLS versions and cipher suites]
 
-[id='property-kafka-bridge-consumer-enabled-config-{context}']
-= `enabled`
-
-Enablement of the consumer can be controlled by setting the `enabled` field to `true` or `false`. Default is `true`.
-
-[id='property-kafka-bridge-consumer-timeout-config-{context}']
-= `timeoutSeconds`
-
-The timeout for deleting inactive consumers can be configured using `timeoutSeconds`, by default it is not enabled.
-
-.Example Kafka Bridge consumer configuration
-[source,yaml,subs="attributes+"]
-----
-apiVersion: {KafkaBridgeApiVersion}
-kind: KafkaBridge
-metadata:
-  name: my-bridge
-spec:
-  # ...
-  consumer:
-    enabled: true
-    timeoutSeconds: 60
-    config:
-      auto.offset.reset: earliest
-      enable.auto.commit: true
-    # ...
-----
-
 IMPORTANT: The Cluster Operator does not validate keys or values in the `config` object.
 If an invalid configuration is provided, the Kafka Bridge deployment might not start or might become unstable.
 In this case, fix the configuration so that the Cluster Operator can roll out the new configuration to all Kafka Bridge nodes.