docs: Add some field level docs

Author: sbernauer

crates/stackable-webhook/src/webhooks/conversion_webhook.rs

@@ -39,11 +39,18 @@ pub enum ConversionWebhookError {
 }
 
 pub struct ConversionWebhook<H> {
+    /// The list of CRDs and their according handlers, which take and return a [`ConversionReview`]
     crds_and_handlers: Vec<(CustomResourceDefinition, H)>,
+
+    /// Whether CRDs should be maintained
     disable_crd_maintenance: bool,
+
+    /// The Kubernetes client used to maintain the CRDs
     client: Client,
-    /// The field manager used when maintaining the CRDs.
+
+    /// The field manager used when maintaining the CRDs
     field_manager: String,
+
     // This channel can only be used exactly once. The sender's send method consumes self, and
     // as such, the sender is wrapped in an Option to be able to call take to consume the inner
     // value.

crates/stackable-webhook/src/webhooks/mutating_webhook.rs

@@ -57,13 +57,13 @@ pub enum MutatingWebhookError {
 /// // The context of the controller, e.g. contains a Kubernetes client
 /// let ctx = Arc::new(());
 /// // Read in from user input, e.g. CLI arguments
-/// let disable_restarter_mutating_webhook = false;
+/// let disable_mutating_webhook_configuration_maintenance = false;
 ///
 /// let mutating_webhook = Box::new(MutatingWebhook::new(
 ///     get_mutating_webhook_configuration(),
 ///     my_handler,
 ///     ctx,
-///     disable_restarter_mutating_webhook,
+///     disable_mutating_webhook_configuration_maintenance,
 ///     client,
 ///     "my-field-manager".to_owned(),
 /// ));
@@ -95,25 +95,37 @@ pub enum MutatingWebhookError {
 /// }
 /// ```
 pub struct MutatingWebhook<H, S, R> {
+    /// The [`MutatingWebhookConfiguration`] that is applied to the Kubernetes cluster.
+    ///
+    /// Your [`MutatingWebhookConfiguration`] can contain 0..n webhooks, but it is recommended to
+    /// only have a single entry in there, as the clientConfig of all entries will be set to the
+    /// same service, port and HTTP path.
+    ///
+    /// All webhooks need to set the `admissionReviewVersions` to `["v1"]`, as this mutating webhook
+    /// only supports that version! A failure to do so will result in a panic during the
+    /// [`MutatingWebhook`] creation.
     mutating_webhook_configuration: MutatingWebhookConfiguration,
+
+    /// The async handler that get's a [`AdmissionRequest`] and returns an [`AdmissionResponse`]
     handler: H,
+
+    /// The internal state of the webhook. You can define yourself what exactly this state is.
     handler_state: Arc<S>,
+
+    /// This field is not needed, it only tracks the type of the Kubernetes resource we are mutating
     _resource: PhantomData<R>,
 
+    /// Whether MutatingWebhookConfigurations should be maintained
     disable_mutating_webhook_configuration_maintenance: bool,
+
+    /// The Kubernetes client used to maintain the MutatingWebhookConfigurations
     client: Client,
 
-    /// The field manager used when maintaining the MutatingWebhookConfigurations.
+    /// The field manager used when maintaining the MutatingWebhookConfigurations
     field_manager: String,
 }
 
 impl<H, S, R> MutatingWebhook<H, S, R> {
-    /// All webhooks need to set the admissionReviewVersions to `["v1"]`, as this mutating webhook
-    /// only supports that version! A failure to do so will result in a panic.
-    ///
-    /// Your [`MutatingWebhookConfiguration`] can contain 0..n webhooks, but it is recommended to
-    /// only have a single entry in there, as the clientConfig of all entries will be set to the
-    /// same service, port and HTTP path.
     pub fn new(
         mutating_webhook_configuration: MutatingWebhookConfiguration,
         handler: H,

crates/stackable-webhook/src/webhooks/validating_webhook.rs

@@ -35,25 +35,37 @@ pub enum ValidatingWebhookError {
 ///
 /// TODO
 pub struct ValidatingWebhook<H, S, R> {
+    /// The [`ValidatingWebhookConfiguration`] that is applied to the Kubernetes cluster.
+    ///
+    /// Your [`ValidatingWebhookConfiguration`] can contain 0..n webhooks, but it is recommended to
+    /// only have a single entry in there, as the clientConfig of all entries will be set to the
+    /// same service, port and HTTP path.
+    ///
+    /// All webhooks need to set the `admissionReviewVersions` to `["v1"]`, as this validating webhook
+    /// only supports that version! A failure to do so will result in a panic during the
+    /// [`ValidatingWebhook`] creation.
     validating_webhook_configuration: ValidatingWebhookConfiguration,
+
+    /// The async handler that get's a [`AdmissionRequest`] and returns an [`AdmissionResponse`]
     handler: H,
+
+    /// The internal state of the webhook. You can define yourself what exactly this state is.
     handler_state: Arc<S>,
+
+    /// This field is not needed, it only tracks the type of the Kubernetes resource we are mutating
     _resource: PhantomData<R>,
 
+    /// Whether ValidatingWebhookConfigurations should be maintained
     disable_validating_webhook_configuration_maintenance: bool,
+
+    /// The Kubernetes client used to maintain the MutatingWebhookConfigurations
     client: Client,
 
     /// The field manager used when maintaining the ValidatingWebhookConfigurations.
     field_manager: String,
 }
 
 impl<H, S, R> ValidatingWebhook<H, S, R> {
-    /// All webhooks need to set the admissionReviewVersions to `["v1"]`, as this validating webhook
-    /// only supports that version! A failure to do so will result in a panic.
-    ///
-    /// Your [`ValidatingWebhookConfiguration`] can contain 0..n webhooks, but it is recommended to
-    /// only have a single entry in there, as the clientConfig of all entries will be set to the
-    /// same service, port and HTTP path.
     pub fn new(
         validating_webhook_configuration: ValidatingWebhookConfiguration,
         handler: H,
@@ -149,6 +161,8 @@ where
 
         let vwc_api: Api<ValidatingWebhookConfiguration> = Api::all(self.client.clone());
         // Other than with the CRDs we don't need to force-apply the ValidatingWebhookConfiguration
+        // This is because the operators are, have been (and likely will be) the only ones creating
+        // them.
         let patch = Patch::Apply(&validating_webhook_configuration);
         let patch_params = PatchParams::apply(&self.field_manager);