doc: Fix references

Author: siegfriedweber

rust/operator-binary/src/controller.rs

@@ -1,4 +1,4 @@
-//! Controller for `v1alpha1::OpenSearchCluster`
+//! Controller for [`v1alpha1::OpenSearchCluster`]
 //!
 //! The cluster specification is validated, Kubernetes resource specifications are created and
 //! applied and the cluster status is updated.
@@ -46,7 +46,7 @@ mod validate;
 
 /// Names in the controller context which are passed to the submodules of the controller
 ///
-/// The names are not directly defined in `Context` because not every submodule requires a
+/// The names are not directly defined in [`Context`] because not every submodule requires a
 /// Kubernetes client and unit testing is easier without an unnecessary client.
 pub struct ContextNames {
     pub product_name: ProductName,
@@ -123,7 +123,7 @@ type OpenSearchRoleGroupConfig =
 type OpenSearchNodeResources =
     stackable_operator::commons::resources::Resources<v1alpha1::StorageConfig>;
 
-/// The validated `v1alpha1::OpenSearchConfig`.
+/// The validated [`v1alpha1::OpenSearchConfig`]
 #[derive(Clone, Debug, PartialEq)]
 pub struct ValidatedOpenSearchConfig {
     pub affinity: StackableAffinity,
@@ -133,14 +133,14 @@ pub struct ValidatedOpenSearchConfig {
     pub listener_class: String,
 }
 
-/// The validated `v1alpha1::OpenSearchCluster`
+/// The validated [`v1alpha1::OpenSearchCluster`]
 ///
 /// Validated means that there should be no reason for Kubernetes to reject resources generated
 /// from these values. This is usually achieved by using fail-safe types. For instance, the cluster
-/// name is wrapped in the type `ClusterName`. This type implements e.g. the function
-/// `ClusterName::to_label_value` which returns a valid label value as string. If this function is
-/// used as intended, i.e. to set a label value, and if it is used as late as possible in the call
-/// chain, then chances are high that the resulting Kubernetes resource is valid.
+/// name is wrapped in the type [`ClusterName`]. This type implements e.g. the function
+/// [`ClusterName::to_label_value`] which returns a valid label value as string. If this function
+/// is used as intended, i.e. to set a label value, and if it is used as late as possible in the
+/// call chain, then chances are high that the resulting Kubernetes resource is valid.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ValidatedCluster {
     metadata: ObjectMeta,
@@ -275,7 +275,7 @@ pub fn error_policy(
 /// Reconcile function of the OpenSearchCluster controller
 ///
 /// The reconcile function performs the following steps:
-/// 1. Validate the given cluster specification and return a `ValidatedCluster` if successful.
+/// 1. Validate the given cluster specification and return a [`ValidatedCluster`] if successful.
 /// 2. Build Kubernetes resource specifications from the validated cluster.
 /// 3. Apply the Kubernetes resource specifications
 /// 4. Update the cluster status
@@ -330,8 +330,8 @@ struct Applied;
 
 /// List of all Kubernetes resources produced by this controller
 ///
-/// `T` is a marker that indicates if these resources are only `Prepared` or already `Applied`. The
-/// marker is useful e.g. to ensure that the cluster status is updated based on the applied
+/// `T` is a marker that indicates if these resources are only [`Prepared`] or already [`Applied`].
+/// The marker is useful e.g. to ensure that the cluster status is updated based on the applied
 /// resources.
 struct KubernetesResources<T> {
     stateful_sets: Vec<StatefulSet>,

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

@@ -31,7 +31,7 @@ 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.
+/// stackable_operator if [`KubernetesResources`] would contain all possible resource types.
 pub struct Applier<'a> {
     client: &'a Client,
     cluster_resources: ClusterResources,

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

@@ -136,7 +136,7 @@ impl NodeConfig {
             == Some(true)
     }
 
-    /// Converts the given JSON value to `bool` if possible
+    /// Converts the given JSON value to [`bool`] if possible
     pub fn value_as_bool(value: &Value) -> Option<bool> {
         value.as_bool().or(
             // OpenSearch parses the strings "true" and "false" as boolean, see
@@ -154,7 +154,7 @@ impl NodeConfig {
     pub fn environment_variables(&self) -> EnvVarSet {
         EnvVarSet::new()
             // Set the OpenSearch node name to the Pod name.
-            // The node name is used e.g. for `{INITIAL_CLUSTER_MANAGER_NODES}`.
+            // The node name is used e.g. for INITIAL_CLUSTER_MANAGER_NODES.
             .with_field_path(
                 EnvVarName::from_str_unsafe(CONFIG_OPTION_NODE_NAME),
                 FieldPathEnvVar::Name,
@@ -189,9 +189,9 @@ impl NodeConfig {
             .join("\n")
     }
 
-    /// Configuration for `{DISCOVERY_TYPE}`
+    /// Configuration for `discovery.type`
     ///
-    /// "zen" is the default if `{DISCOVERY_TYPE}` is not set.
+    /// "zen" is the default if `discovery.type` is not set.
     /// It is nevertheless explicitly set here.
     /// see <https://github.com/opensearch-project/OpenSearch/blob/3.0.0/server/src/main/java/org/opensearch/discovery/DiscoveryModule.java#L88-L89>
     ///
@@ -236,7 +236,7 @@ impl NodeConfig {
                 .cluster
                 .role_group_configs_filtered_by_node_role(&v1alpha1::NodeRole::ClusterManager);
 
-            // This setting requires node names as set in `{NODE_NAME}`.
+            // This setting requires node names as set in NODE_NAME.
             // The node names are set to the pod names with
             // `valueFrom.fieldRef.fieldPath: metadata.name`, so it is okay to calculate the pod
             // names here and use them as node names.

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

@@ -103,7 +103,7 @@ impl<'a> RoleBuilder<'a> {
     /// Builds a Service that references all nodes with the cluster_manager node role
     ///
     /// Initially, this service was meant to be used by
-    /// `NodeConfig::initial_cluster_manager_nodes`, but the function uses now another approach.
+    /// [`super::node_config::NodeConfig::initial_cluster_manager_nodes`], but the function uses now another approach.
     /// Afterwards, it was meant to be used as an entry point to OpenSearch, but it could also make
     /// sense to use coordinating only nodes as entry points and not cluster manager nodes.
     /// Therefore, this service will bei either adapted or removed. There is already an according
@@ -144,7 +144,7 @@ impl<'a> RoleBuilder<'a> {
         }
     }
 
-    /// Builds a PodDisruptionBudget used by all role-groups
+    /// Builds a [`PodDisruptionBudget`] used by all role-groups
     pub fn build_pdb(&self) -> Option<PodDisruptionBudget> {
         let pdb_config = &self.cluster.role_config.pod_disruption_budget;
 

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

@@ -103,7 +103,8 @@ impl<'a> RoleGroupBuilder<'a> {
         }
     }
 
-    /// Builds the ConfigMap containing the configuration files of the role-group StatefulSet
+    /// Builds the [`ConfigMap`] containing the configuration files of the role-group
+    /// [`StatefulSet`]
     pub fn build_config_map(&self) -> ConfigMap {
         let metadata = self
             .common_metadata(self.resource_names.role_group_config_map())
@@ -122,7 +123,7 @@ impl<'a> RoleGroupBuilder<'a> {
         }
     }
 
-    /// Builds the role-group StatefulSet
+    /// Builds the role-group [`StatefulSet`]
     pub fn build_stateful_set(&self) -> StatefulSet {
         let metadata = self
             .common_metadata(self.resource_names.stateful_set_name())
@@ -177,7 +178,7 @@ impl<'a> RoleGroupBuilder<'a> {
         }
     }
 
-    /// Builds the PodTemplateSpec for the role-group StatefulSet
+    /// Builds the [`PodTemplateSpec`] for the role-group [`StatefulSet`]
     fn build_pod_template(&self) -> PodTemplateSpec {
         let mut node_role_labels = Labels::new();
         for node_role in self.role_group_config.config.node_roles.iter() {
@@ -245,8 +246,8 @@ impl<'a> RoleGroupBuilder<'a> {
 
     /// Returns the labels of OpenSearch nodes with the `cluster_manager` role.
     ///
-    /// As described in `RoleBuilder::build_cluster_manager_service`, this function will be
-    /// changed or deleted.
+    /// As described in [`super::role_builder::RoleBuilder::build_cluster_manager_service`], this
+    /// function will be changed or deleted.
     pub fn cluster_manager_labels(
         cluster: &ValidatedCluster,
         context_names: &ContextNames,
@@ -275,7 +276,7 @@ impl<'a> RoleGroupBuilder<'a> {
         .expect("should be a valid label")
     }
 
-    /// Builds the container for the PodTemplateSpec
+    /// Builds the container for the [`PodTemplateSpec`]
     fn build_container(&self, role_group_config: &OpenSearchRoleGroupConfig) -> Container {
         let product_image = self
             .cluster
@@ -312,7 +313,7 @@ impl<'a> RoleGroupBuilder<'a> {
             .get(EnvVarName::from_str_unsafe("OPENSEARCH_HOME"))
             .and_then(|env_var| env_var.value.clone())
             .unwrap_or(DEFAULT_OPENSEARCH_HOME.to_owned());
-        // Use `OPENSEARCH_PATH_CONF` from envOverrides or default to `{OPENSEARCH_HOME}/config`,
+        // Use `OPENSEARCH_PATH_CONF` from envOverrides or default to `OPENSEARCH_HOME/config`,
         // i.e. depend on `OPENSEARCH_HOME`.
         let opensearch_path_conf = env_vars
             .get(EnvVarName::from_str_unsafe("OPENSEARCH_PATH_CONF"))
@@ -367,7 +368,7 @@ impl<'a> RoleGroupBuilder<'a> {
             .build()
     }
 
-    /// Builds the headless Service for the role-group
+    /// Builds the headless [`Service`] for the role-group
     pub fn build_headless_service(&self) -> Service {
         let metadata = self
             .common_metadata(self.resource_names.headless_service_name())
@@ -437,7 +438,7 @@ impl<'a> RoleGroupBuilder<'a> {
         .expect("should be valid annotations")
     }
 
-    /// Builds the Listener for the role-group
+    /// Builds the [`listener::v1alpha1::Listener`] for the role-group
     ///
     /// The Listener exposes only the HTTP port.
     /// The Listener operator will create a Service per role-group.
@@ -495,7 +496,9 @@ impl<'a> RoleGroupBuilder<'a> {
         )
     }
 
-    /// Labels to select a Pod in the role-group
+    /// Labels to select a [`Pod`] in the role-group
+    ///
+    /// [`Pod`]: stackable_operator::k8s_openapi::api::core::v1::Pod
     fn pod_selector(&self) -> Labels {
         role_group_selector(
             &self.cluster,

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

@@ -34,7 +34,8 @@ 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
+/// 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

@@ -69,7 +69,7 @@ pub enum Error {
 
 type Result<T, E = Error> = std::result::Result<T, E>;
 
-/// Validates the `v1alpha1::OpenSearchCluster` and returns a `ValidateCluster`
+/// Validates the [`v1alpha1::OpenSearchCluster`] and returns a [`ValidatedCluster`]
 ///
 /// The validated values should be wrapped in fail-safe types so that illegal states are
 /// unrepresentable in the following steps.

rust/operator-binary/src/framework.rs

@@ -1,24 +1,24 @@
 //! Additions to stackable-operator
 //!
 //! Functions in stackable-operator usually accept generic types like strings and validate the
-//! parameters as late as possible. Therefore, nearly all functions have to return a `Result` and
+//! parameters as late as possible. Therefore, nearly all functions have to return a [`Result`] and
 //! errors are returned along the call chain. That makes error handling complex because every
 //! module re-packages the received error. Also, the validation is repeated if the value is used in
 //! different function calls. Sometimes, validation is not necessary if constant values are used,
 //! e.g. the name of the operator.
 //!
 //! The OpenSearch operator uses a different approach. The incoming values are validated as early
 //! as possible and wrapped in a fail-safe type. This type is then used along the call chain,
-//! validation is not necessary anymore and functions without side effects do not need to return
-//! a `Result`.
+//! validation is not necessary anymore and functions without side effects do not need to return a
+//! [`Result`].
 //!
 //! However, the OpenSearch operator uses stackable-operator and at the interface, the fail-safe
-//! types must be unwrapped and the `Result` returned by the stackable-operator function must be
-//! handled. This is done by calling `Result::expect` which requires thorough testing.
+//! types must be unwrapped and the [`Result`] returned by the stackable-operator function must be
+//! handled. This is done by calling [`Result::expect`] which requires thorough testing.
 //!
 //! When the development of the OpenSearch operator has progressed and changes in this module
-//! become less frequent, then this module can be incorporated into stackable-operator. The
-//! module structure should already resemble the one of stackable-operator.
+//! become less frequent, then this module can be incorporated into stackable-operator. The module
+//! structure should already resemble the one of stackable-operator.
 
 use std::{fmt::Display, str::FromStr};
 
@@ -63,17 +63,18 @@ pub enum Error {
 
 /// Maximum length of DNS subdomain names as defined in RFC 1123.
 ///
-/// Duplicates the private constant `stackable-operator::validation::RFC_1123_SUBDOMAIN_MAX_LENGTH`
+/// Duplicates the private constant
+/// [`stackable-operator::validation::RFC_1123_SUBDOMAIN_MAX_LENGTH`]
 pub const MAX_RFC_1123_DNS_SUBDOMAIN_NAME_LENGTH: usize = 253;
 
 /// Maximum length of label names as defined in RFC 1123.
 ///
-/// Duplicates the private constant `stackable-operator::validation::RFC_1123_LABEL_MAX_LENGTH`
+/// Duplicates the private constant [`stackable-operator::validation::RFC_1123_LABEL_MAX_LENGTH`]
 pub const MAX_RFC_1123_LABEL_NAME_LENGTH: usize = 63;
 
 /// Maximum length of label values
 ///
-/// Duplicates the private constant `stackable-operator::kvp::label::value::LABEL_VALUE_MAX_LEN`
+/// Duplicates the private constant [`stackable-operator::kvp::label::value::LABEL_VALUE_MAX_LEN`]
 pub const MAX_LABEL_VALUE_LENGTH: usize = 63;
 
 /// Has a non-empty name
@@ -213,7 +214,7 @@ macro_rules! attributed_string_type {
 
 /// Returns the minimum of the given values.
 ///
-/// As opposed to `std::cmp::min`, this function can be used at compile-time.
+/// As opposed to [`std::cmp::min`], this function can be used at compile-time.
 ///
 /// # Examples
 ///

rust/operator-binary/src/framework/builder/meta.rs

@@ -5,7 +5,8 @@ use stackable_operator::{
 
 use crate::framework::{HasName, HasUid};
 
-/// Infallible variant of `stackable_operator::builder::meta::ObjectMetaBuilder::ownerreference_from_resource`
+/// Infallible variant of
+/// [`stackable_operator::builder::meta::ObjectMetaBuilder::ownerreference_from_resource`]
 pub fn ownerreference_from_resource(
     resource: &(impl Resource<DynamicType = ()> + HasName + HasUid),
     block_owner_deletion: Option<bool>,

rust/operator-binary/src/framework/builder/pdb.rs

@@ -9,7 +9,7 @@ use crate::framework::{
 };
 
 /// Infallible variant of
-/// `stackable_operator::builder::pdb::PodDisruptionBudgetBuilder::new_with_role`
+/// [`stackable_operator::builder::pdb::PodDisruptionBudgetBuilder::new_with_role`]
 pub fn pod_disruption_budget_builder_with_role(
     owner: &(impl Resource<DynamicType = ()> + HasName + NameIsValidLabelValue + HasUid),
     product_name: &ProductName,