doc: Add code comments

Author: siegfriedweber

rust/operator-binary/src/controller/apply.rs

@@ -26,6 +26,10 @@ pub enum Error {
 
 type Result<T, E = Error> = std::result::Result<T, E>;
 
+/// Applier for the Kubernetes resource specifications produced by this controller
+///
+/// The implementation is not tied to this controller and could theoretically be moved to
+/// stackable_operator if `KubernetesResources` would contain all possible resource types.
 pub struct Applier<'a> {
     client: &'a Client,
     cluster_resources: ClusterResources,
@@ -56,6 +60,7 @@ impl<'a> Applier<'a> {
         }
     }
 
+    /// Applies the given Kubernetes resources and marks them as applied
     pub async fn apply(
         mut self,
         resources: KubernetesResources<Prepared>,

rust/operator-binary/src/controller/build.rs

@@ -8,6 +8,13 @@ pub mod node_config;
 pub mod role_builder;
 pub mod role_group_builder;
 
+/// Builds Kubernetes resource specifications from the given validated cluster
+///
+/// This function cannot fail because all failing conditions were already checked in the validation
+/// step.
+/// A Kubernetes client is not required because references to other Kubernetes resources must
+/// already be dereferenced in a prior step and the result would be validated and added to the
+/// validated cluster.
 pub fn build(names: &ContextNames, cluster: ValidatedCluster) -> KubernetesResources<Prepared> {
     let mut config_maps = vec![];
     let mut stateful_sets = vec![];

rust/operator-binary/src/controller/build/role_builder.rs

@@ -177,11 +177,11 @@ impl<'a> RoleBuilder<'a> {
         .unwrap();
 
         let managed_by = Label::managed_by(
-            &self.context_names.operator_name.to_string(),
-            &self.context_names.controller_name.to_string(),
+            self.context_names.operator_name.as_ref(),
+            self.context_names.controller_name.as_ref(),
         )
         .unwrap();
-        let version = Label::version(&self.cluster.product_version.to_string()).unwrap();
+        let version = Label::version(self.cluster.product_version.as_ref()).unwrap();
 
         labels.insert(managed_by);
         labels.insert(version);

rust/operator-binary/src/controller/update_status.rs

@@ -32,6 +32,7 @@ pub enum Error {
 
 type Result<T, E = Error> = std::result::Result<T, E>;
 
+/// Updates the status of the `v1alpha1::OpenSearchCluster` according to the given applied resources
 pub async fn update_status(
     client: &Client,
     names: &ContextNames,

rust/operator-binary/src/controller/validate.rs

@@ -67,7 +67,13 @@ pub enum Error {
 
 type Result<T, E = Error> = std::result::Result<T, E>;
 
-// no client needed
+/// Validates the `v1alpha1::OpenSearchCluster` and returns a `ValidateCluster`
+///
+/// The validated values should be wrapped in fail-safe types so that illegal states are
+/// unrepresentable in the following steps.
+///
+/// A Kubernetes client is not required because references to other Kubernetes resources must
+/// already be dereferenced in a prior step.
 pub fn validate(
     context_names: &ContextNames,
     cluster: &v1alpha1::OpenSearchCluster,

rust/operator-binary/src/framework/builder/pod/container.rs

@@ -17,10 +17,14 @@ pub enum Error {
     ParseEnvVarName { env_var_name: String },
 }
 
+/// Validated environment variable name
 #[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct EnvVarName(String);
 
 impl EnvVarName {
+    /// Creates an `EnvVarName` from the given string and panics if the validation failed
+    ///
+    /// Use this only with constant names that are also tested in unit tests!
     pub fn from_str_unsafe(s: &str) -> Self {
         EnvVarName::from_str(s).expect("should be a valid environment variable name")
     }
@@ -36,7 +40,7 @@ impl FromStr for EnvVarName {
     type Err = Error;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
-        // The length of the environment variable names seems not to be restricted.
+        // The length of environment variable names seems not to be restricted.
 
         if !s.is_empty() && s.chars().all(|c| matches!(c, ' '..='<' | '>'..='~')) {
             Ok(Self(s.to_owned()))
@@ -48,24 +52,35 @@ impl FromStr for EnvVarName {
     }
 }
 
+/// A set of `EnvVar`s
+///
+/// The environment variable names in the set are unique.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct EnvVarSet(BTreeMap<EnvVarName, EnvVar>);
 
 impl EnvVarSet {
+    /// Creates an empty `EnvVarSet`
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Returns a reference to the `EnvVar` with the given name
     pub fn get(&self, env_var_name: impl Into<EnvVarName>) -> Option<&EnvVar> {
         self.0.get(&env_var_name.into())
     }
 
+    /// Moves all `EnvVar`s from the given set into this one.
+    ///
+    /// `EnvVar`s with the same name are overridden.
     pub fn merge(mut self, mut env_var_set: EnvVarSet) -> Self {
         self.0.append(&mut env_var_set.0);
 
         self
     }
 
+    /// Adds the given `EnvVar`s to this set
+    ///
+    /// `EnvVar`s with the same name are overridden.
     pub fn with_values<I, K, V>(self, env_vars: I) -> Self
     where
         I: IntoIterator<Item = (K, V)>,
@@ -79,6 +94,9 @@ impl EnvVarSet {
             })
     }
 
+    /// Adds an environment variable with the given name and string value to this set
+    ///
+    /// An `EnvVar` with the same name is overridden.
     pub fn with_value(mut self, name: impl Into<EnvVarName>, value: impl Into<String>) -> Self {
         let name: EnvVarName = name.into();
 
@@ -94,6 +112,9 @@ impl EnvVarSet {
         self
     }
 
+    /// Adds an environment variable with the given name and field path to this set
+    ///
+    /// An `EnvVar` with the same name is overridden.
     pub fn with_field_path(
         mut self,
         name: impl Into<EnvVarName>,

rust/operator-binary/src/framework/role_group_utils.rs

@@ -3,6 +3,7 @@ use std::str::FromStr;
 use super::{ClusterName, ConfigMapName, ListenerName, RoleGroupName, RoleName, StatefulSetName};
 use crate::framework::ServiceName;
 
+/// Type-safe names for role-group resources
 pub struct ResourceNames {
     pub cluster_name: ClusterName,
     pub role_name: RoleName,

rust/operator-binary/src/framework/role_utils.rs

@@ -20,14 +20,21 @@ use super::{
 };
 use crate::framework::{ClusterName, ClusterRoleName};
 
+/// Variant of `stackable_operator::role_utils::GenericProductSpecificCommonConfig` that implements
+/// `Merge`
 #[derive(Clone, Debug, Default, Deserialize, JsonSchema, PartialEq, Serialize)]
 pub struct GenericProductSpecificCommonConfig {}
 
 impl Merge for GenericProductSpecificCommonConfig {
     fn merge(&mut self, _defaults: &Self) {}
 }
 
-// much better to work with than RoleGroup
+/// Variant of `stackable_operator::role_utils::RoleGroup` that is easier to work with
+///
+/// Differences are:
+/// * `replicas` is non-optional.
+/// * `config` is flattened.
+/// * The `HashMap` in `env_overrides` is replaced with an `EnvVarSet`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct RoleGroupConfig<ProductSpecificCommonConfig, T> {
     pub replicas: u16,
@@ -51,7 +58,9 @@ impl<ProductSpecificCommonConfig, T> RoleGroupConfig<ProductSpecificCommonConfig
     }
 }
 
-// RoleGroup::validate_config with fixed types
+/// Variant of `stackable_operator::role_utils::RoleGroup::validate_config` with fixed types
+///
+/// The `role` parameter takes the `ProductSpecificCommonConfig` into account.
 pub fn validate_config<C, ProductSpecificCommonConfig, T, U>(
     role_group: &RoleGroup<T, ProductSpecificCommonConfig>,
     role: &Role<T, U, ProductSpecificCommonConfig>,
@@ -70,7 +79,7 @@ where
     fragment::validate(rolegroup_config)
 }
 
-// also useful for operators which use the product config
+/// Merges and validates the `RoleGroup` with the given `role` and `default_config`
 pub fn with_validated_config<C, ProductSpecificCommonConfig, T, U>(
     role_group: &RoleGroup<T, ProductSpecificCommonConfig>,
     role: &Role<T, U, ProductSpecificCommonConfig>,
@@ -161,6 +170,7 @@ where
     merge(role_group_config, &role_config)
 }
 
+/// Type-safe names for role resources
 pub struct ResourceNames {
     pub cluster_name: ClusterName,
     pub product_name: ProductName,