add more documentation on flow

Signed-off-by: clux <[email protected]>

kube-core/src/admission.rs

@@ -40,6 +40,11 @@ pub const META_API_VERSION_V1BETA1: &str = "admission.k8s.io/v1beta1";
 
 /// The top level struct used for Serializing and Deserializing AdmissionReview
 /// requests and responses.
+///
+/// This is both the input type received by admission controllers, and the
+/// output type admission controllers should return.
+///
+/// An admission controller should start by inspecting the [`AdmissionRequest`].
 #[derive(Serialize, Deserialize, Clone, Debug)]
 #[serde(rename_all = "camelCase")]
 pub struct AdmissionReview<T: Resource> {
@@ -70,13 +75,25 @@ impl<T: Resource> TryInto<AdmissionRequest<T>> for AdmissionReview<T> {
 }
 
 /// An incoming [`AdmissionReview`] request.
+///
+/// In an admission controller scenario, this is extracted from an [`AdmissionReview`] via [`TryInto`]
+///
 /// ```ignore
 /// use kube::api::{admission::{AdmissionRequest, AdmissionReview}, DynamicObject};
 ///
 /// // The incoming AdmissionReview received by the controller.
 /// let body: AdmissionReview<DynamicObject>;
 /// let req: AdmissionRequest<_> = body.try_into().unwrap();
 /// ```
+///
+/// Based on the contents of the request, an admission controller should construct an
+/// [`AdmissionResponse`] using:
+///
+/// - [`AdmissionResponse::deny`] for illegal/rejected requests
+/// - [`AdmissionResponse::invalid`] for malformed requests
+/// - [`AdmissionResponse::from`] for the happy path
+///
+/// then wrap the chosen response in an [`AdmissionReview`] via [`AdmissionResponse::into_review`].
 #[derive(Serialize, Deserialize, Clone, Debug)]
 #[serde(rename_all = "camelCase")]
 pub struct AdmissionRequest<T: Resource> {