docs(webhook): Add example for ConversionWebhookServer::with_maintainer

Author: Techassi

crates/stackable-webhook/src/servers/conversion.rs

@@ -189,7 +189,76 @@ impl ConversionWebhookServer {
     /// Creates and returns a tuple consisting of a [`ConversionWebhookServer`], a [`CustomResourceDefinitionMaintainer`],
     /// and a [`oneshot::Receiver`].
     ///
+    /// ## Parameters
+    ///
+    /// - `crds_and_handlers`: An iterator over a 2-tuple (pair) mapping a [`CustomResourceDefinition`]
+    ///   to a handler function. In most cases, the generated `CustomResource::try_merge` function
+    ///   should be used. It provides the expected `fn(ConversionReview) -> ConversionReview`
+    ///   signature.
+    /// - `operator_name`: The name of the operator. This is used to construct the webhook service
+    ///   name.
+    /// - `operator_namespace`: The namespace the operator runs in. This is used to construct the
+    ///   webhook service name.
+    /// - `disable_maintainer`: A boolean value to indicate if the [`CustomResourceDefinitionMaintainer`]
+    ///   should be disabled.
+    /// - `client`: A [`kube::Client`] used to maintain the custom resource definitions.
+    ///
     /// See the referenced items for more details on usage.
+    ///
+    /// ## Return Values
+    ///
+    /// - The [`ConversionWebhookServer`] itself. This is used to run the server. See
+    ///   [`ConversionWebhookServer::run`] for more details.
+    /// - The [`CustomResourceDefinitionMaintainer`] which is used to run the maintainer. See
+    ///   [`CustomResourceDefinitionMaintainer::run`] for more details.
+    /// - A [`oneshot::Receiver`] which is triggered after the initial reconciliation of the CRDs
+    ///   succeeded. This signal can be used to deploy any custom resources defined by these CRDs.
+    ///
+    /// ## Example
+    ///
+    /// ```no_run
+    /// # use futures_util::TryFutureExt;
+    /// # use tokio_rustls::rustls::crypto::{CryptoProvider, ring::default_provider};
+    /// use stackable_webhook::servers::{ConversionWebhookServer, ConversionWebhookOptions};
+    /// use stackable_operator::{kube::Client, crd::s3::{S3Connection, S3ConnectionVersion}};
+    ///
+    /// # #[tokio::main]
+    /// # async fn main() {
+    /// # CryptoProvider::install_default(default_provider()).unwrap();
+    /// let client = Client::try_default().await.unwrap();
+    ///
+    /// let crds_and_handlers = vec![
+    ///     (
+    ///         S3Connection::merged_crd(S3ConnectionVersion::V1Alpha1)
+    ///             .expect("the S3Connection CRD must be merged"),
+    ///         S3Connection::try_convert,
+    ///     )
+    /// ];
+    ///
+    /// let (conversion_webhook_server, crd_maintainer, _initial_reconcile_rx) =
+    ///     ConversionWebhookServer::with_maintainer(
+    ///         crds_and_handlers,
+    ///         "my-operator",
+    ///         "my-namespace",
+    ///         false,
+    ///         client,
+    ///     )
+    ///     .await
+    ///     .unwrap();
+    ///
+    /// let conversion_webhook_server = conversion_webhook_server
+    ///     .run()
+    ///     .map_err(|err| err.to_string());
+    ///
+    /// let crd_maintainer = crd_maintainer
+    ///     .run()
+    ///     .map_err(|err| err.to_string());
+    ///
+    /// // Run both the conversion webhook server and crd_maintainer concurrently, eg. with
+    /// // futures::try_join!.
+    /// futures_util::try_join!(conversion_webhook_server, crd_maintainer).unwrap();
+    /// # }
+    /// ```
     pub async fn with_maintainer<'a, H>(
         // TODO (@Techassi): Use a trait type here which can be used to build all part of the
         // conversion webhook server and a CRD maintainer.