Add some docs

Author: sbernauer

crates/stackable-webhook/src/lib.rs

@@ -72,6 +72,12 @@ impl WebhookServer {
     pub const DEFAULT_SOCKET_ADDRESS: SocketAddr =
         SocketAddr::new(Self::DEFAULT_LISTEN_ADDRESS, Self::DEFAULT_HTTPS_PORT);
 
+    /// Creates a new webhook server with the given config and list of webhooks.
+    ///
+    /// Currently the webhooks [`ConversionWebhook`](servers::ConversionWebhook) and
+    /// [`MutatingWebhook`](servers::MutatingWebhook) are implemented.
+    ///
+    /// Please read their documentation for details.
     pub async fn new(
         options: WebhookServerOptions,
         webhooks: Vec<Box<dyn Webhook>>,

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

@@ -24,12 +24,21 @@ pub enum WebhookError {
     },
 }
 
+/// A webhook (such as a conversion or mutating webhook) needs to implement this trait.
+//
 // We still need to use the async-trait crate, as Rust 1.91.1 does not support dynamic dispatch
 // in combination with async functions.
 #[async_trait]
 pub trait Webhook {
+    /// The webhook can add arbitrary routes to the passed [`Router`] and needs to return the
+    /// resulting [`Router`].
     fn register_routes(&self, router: Router) -> Router;
 
+    /// The HTTPS server periodically rotates it's certificate.
+    ///
+    /// Typically, some caller of the webhook (e.g. Kubernetes) needs to know the certificate to be
+    /// able to establish the TLS connection.
+    /// Webhooks are informed about new certificates by this function and can react accordingly.
     async fn handle_certificate_rotation(
         &mut self,
         new_certificate: &Certificate,

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

@@ -33,7 +33,7 @@ pub enum MutatingWebhookError {
 /// on the fly.
 ///
 /// As the webhook is typed with the Resource type `R`, it can only handle a single resource
-/// mutation. Use multiple [`MutatingWebhookServer`] if you need to mutate multiple resource kinds.
+/// mutation. Use multiple [`MutatingWebhook`] if you need to mutate multiple resource kinds.
 ///
 /// ### Example usage
 ///