Review and update descriptions for schema (#1772)

* Review and update descriptions for schema

* Correct typos

* Review comments

* More comments

* A couple more, minor changes

* A couple more missing periods

* Even more review

Author: rjeberhard

docs/domains/Domain.json

@@ -12,12 +12,12 @@
 import org.apache.commons.lang3.builder.HashCodeBuilder;
 import org.apache.commons.lang3.builder.ToStringBuilder;
 
-@Description("AdminServer represents the operator configuration for the Administration Server.")
 public class AdminServer extends Server {
 
   @Description(
-      "Configures which of the Administration Server's WebLogic admin channels should be exposed outside"
-          + " the Kubernetes cluster via a node port service.")
+      "Customization affecting the generation of the Kubernetes Service for the Administration Server. These settings "
+      + "can also specify the creation of a second NodePort Service to expose specific channels or network access "
+      + "points outside the Kubernetes cluster.")
   private AdminService adminService;
 
   /**

docs/domains/Domain.md

@@ -20,15 +20,15 @@ public class AdminService implements ServiceConfigurator {
   @SerializedName("channels")
   @Description(
       "Specifies which of the Administration Server's WebLogic channels should be exposed outside "
-          + "the Kubernetes cluster via a node port service, along with the node port for "
-          + "each channel. If not specified, the Administration Server's node port service will "
+          + "the Kubernetes cluster via a NodePort Service, along with the port for "
+          + "each channel. If not specified, the Administration Server's NodePort Service will "
           + "not be created.")
   private final List<Channel> channels = new ArrayList<>();
 
-  @Description("Labels to associate with the external channel service.")
+  @Description("Labels to associate with the Administration Server's Service(s).")
   private final Map<String, String> labels = new HashMap<>();
 
-  @Description("Annotations to associate with the external channel service.")
+  @Description("Annotations to associate with the Administration Server's Service(s).")
   private final Map<String, String> annotations = new HashMap<>();
 
   /**

docs/domains/index.html

@@ -35,19 +35,19 @@
  */
 public abstract class BaseConfiguration {
 
-  @Description("Configuration affecting server pods.")
+  @Description("Customization affecting the generation of Pods for WebLogic Server instances.")
   private final ServerPod serverPod = new ServerPod();
 
   @Description(
-      "Customization affecting ClusterIP Kubernetes services for WebLogic Server instances.")
+      "Customization affecting the generation of Kubernetes Services for WebLogic Server instances.")
   @SerializedName("serverService")
   @Expose
   private final ServerService serverService = new ServerService();
 
   /** Desired startup state. Legal values are RUNNING or ADMIN. */
   @EnumClass(ServerStartState.class)
   @Description(
-      "The state in which the server is to be started. Use ADMIN if server should start "
+      "The WebLogic runtime state in which the server is to be started. Use ADMIN if the server should start "
           + "in the admin state. Defaults to RUNNING.")
   private String serverStartState;
 
@@ -61,8 +61,9 @@ public abstract class BaseConfiguration {
    * @since 2.0
    */
   @Description(
-      "If present, every time this value is updated the operator will restart"
-          + " the required servers.")
+      "Changes to this field cause the operator to restart WebLogic Server instances. More info: "
+      + "https://oracle.github.io/weblogic-kubernetes-operator/userguide/managing-domains/"
+      + "domain-lifecycle/startup/#restarting-servers.")
   private String restartVersion;
 
   /**

kubernetes/crd/domain-crd.yaml

@@ -11,25 +11,24 @@
 import org.apache.commons.lang3.builder.HashCodeBuilder;
 import org.apache.commons.lang3.builder.ToStringBuilder;
 
-@Description("Describes a single channel used by the Administration Server.")
 public class Channel implements Comparable<Channel> {
   @SerializedName("channelName")
   @Description(
-      "Name of channel.\n'default' refers to the Administration Server's default channel (configured "
-          + "via the ServerMBean's ListenPort) "
-          + "\n'default-secure' refers to the Administration Server's default secure channel "
-          + "(configured via the ServerMBean's SSLMBean's ListenPort) "
-          + "\n'default-admin' refers to the Administration Server's default administrative channel "
-          + "(configured via the DomainMBean's AdministrationPort) "
-          + "\nOtherwise, the name is the name of one of the Administration Server's network access points "
-          + "(configured via the ServerMBean's NetworkAccessMBeans).")
+      "Name of the channel. The \"default\" value refers to the Administration Server's default channel, "
+          + "which is configured using the ServerMBean's ListenPort. "
+          + "The \"default-secure\" value refers to the Administration Server's default secure channel, "
+          + "which is configured using the ServerMBean's SSLMBean's ListenPort. "
+          + "The \"default-admin\" value refers to the Administration Server's default administrative channel, "
+          + "which is configured using the DomainMBean's AdministrationPort. "
+          + "Otherwise, provide the name of one of the Administration Server's network access points, "
+          + "which is configured using the ServerMBean's NetworkAccessMBeans. The \"default\", \"default-secure\", "
+          + "and \"default-admin\" channels may not be specified here when using Istio.")
   @Nonnull
   private String channelName;
 
   @SerializedName("nodePort")
   @Description(
-      "Specifies the port number used to access the WebLogic channel "
-          + "outside of the Kubernetes cluster. "
+      "Specifies the port number used to access the WebLogic channel outside of the Kubernetes cluster. "
           + "If not specified, defaults to the port defined by the WebLogic channel.")
   private Integer nodePort;
 

kubernetes/crd/domain-v1beta1-crd.yaml

@@ -22,15 +22,27 @@
  *
  * @since 2.0
  */
-@Description("An element representing a cluster in the domain configuration.")
 public class Cluster extends BaseConfiguration implements Comparable<Cluster> {
   /** The name of the cluster. Required. */
-  @Description("The name of this cluster. Required")
+  @Description("The name of the cluster. This value must match the name of a WebLogic cluster already defined "
+      + "in the WebLogic domain configuration. Required.")
   @Nonnull
   private String clusterName;
 
   /** The number of replicas to run in the cluster, if specified. */
-  @Description("The number of cluster members to run.")
+  @Description(
+      "The number of cluster member Managed Server instances to start for this WebLogic cluster. "
+      + "The operator will sort cluster member Managed Server names from the WebLogic domain "
+      + "configuration by normalizing any numbers in the Managed Server name and then sorting alphabetically. "
+      + "This is done so that server names such as \"managed-server10\" come after \"managed-server9\". "
+      + "The operator will then start Managed Server instances from the sorted list, "
+      + "up to the `replicas` count, unless specific Managed Servers are specified as "
+      + "starting in their entry under the `managedServers` field. In that case, the specified Managed Server "
+      + "instances will be started and then additional cluster members "
+      + "will be started, up to the `replicas` count, by finding further cluster members in the sorted list that are "
+      + "not already started. If cluster members are started "
+      + "because of their related entries under `managedServers`, then this cluster may have more cluster members "
+      + "running than its `replicas` count. Defaults to 0.")
   @Range(minimum = 0)
   private Integer replicas;
 
@@ -42,34 +54,36 @@ public class Cluster extends BaseConfiguration implements Comparable<Cluster> {
    * @since 2.0
    */
   @EnumClass(value = ServerStartPolicy.class, qualifier = "forCluster")
-  @Description(
-      "The strategy for deciding whether to start a server. "
-          + "Legal values are NEVER, or IF_NEEDED.")
+  @Description("The strategy for deciding whether to start a WebLogic Server instance. "
+      + "Legal values are NEVER, or IF_NEEDED. Defaults to IF_NEEDED. "
+      + "More info: https://oracle.github.io/weblogic-kubernetes-operator/userguide/managing-domains/"
+      + "domain-lifecycle/startup/#starting-and-stopping-servers.")
   private String serverStartPolicy;
 
   @Description(
       "The maximum number of cluster members that can be temporarily unavailable. Defaults to 1.")
   @Range(minimum = 1)
   private Integer maxUnavailable;
 
-  @Description("Customization affecting ClusterIP Kubernetes services for the WebLogic cluster.")
+  @Description("Customization affecting Kubernetes Service generated for this WebLogic cluster.")
   @SerializedName("clusterService")
   @Expose
   private KubernetesResource clusterService = new KubernetesResource();
 
-  @Description("If true (the default), then the number of replicas is allowed to drop below the "
-      + "minimum dynamic cluster size configured in the WebLogic domain home configuration. "
-      + "Otherwise, the operator will ensure that the number of replicas is not less than "
-      + "the minimum dynamic cluster setting. This setting applies to dynamic clusters only."
+  @Description("Specifies whether the number of running cluster members is allowed to drop below the "
+      + "minimum dynamic cluster size configured in the WebLogic domain configuration. "
+      + "Otherwise, the operator will ensure that the number of running cluster members is not less than "
+      + "the minimum dynamic cluster setting. This setting applies to dynamic clusters only. "
+      + "Defaults to true."
   )
   private Boolean allowReplicasBelowMinDynClusterSize;
 
   @Description(
-      "The maximum number of Managed Servers that the operator will start in parallel "
-      + "for the cluster in response to a change in replicas count for the cluster. "
-      + "If more Managed Servers need to be started, the operator will wait until a Managed "
-      + "Server pod is in the `Ready` and `Running` state before starting the next Managed Server. "
-      + "A value of 0 (the default) means all Managed Servers will start in parallel."
+      "The maximum number of Managed Servers instances that the operator will start in parallel "
+      + "for this cluster in response to a change in the `replicas` count. "
+      + "If more Managed Server instances must be started, the operator will wait until a Managed "
+      + "Server Pod is in the `Ready` state before starting the next Managed Server instance. "
+      + "A value of 0 means all Managed Server instances will start in parallel. Defaults to 0."
   )
   @Range(minimum = 0)
   private Integer maxConcurrentStartup;