From 1233492553f7e7c0bdc7a3ce20169ee127b620d1 Mon Sep 17 00:00:00 2001 From: Mikail Bagishov Date: Tue, 6 Sep 2022 00:12:13 +0300 Subject: [PATCH] Improve docs --- kube-core/src/conversion/types.rs | 59 ++++++++++++++++++------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/kube-core/src/conversion/types.rs b/kube-core/src/conversion/types.rs index c5827ad87..a08603727 100644 --- a/kube-core/src/conversion/types.rs +++ b/kube-core/src/conversion/types.rs @@ -2,26 +2,26 @@ use crate::{Status, TypeMeta}; use serde::{Deserialize, Serialize}; use thiserror::Error; -/// The `kind` field in [`TypeMeta`]. +/// The `kind` field in [`TypeMeta`] pub const META_KIND: &str = "ConversionReview"; -/// The `api_version` field in [`TypeMeta`] on the v1 version. +/// The `api_version` field in [`TypeMeta`] on the v1 version pub const META_API_VERSION_V1: &str = "apiextensions.k8s.io/v1"; #[derive(Debug, Error)] #[error("request missing in ConversionReview")] -/// Failed to convert `AdmissionReview` into `AdmissionRequest`. +/// Returned when `AdmissionReview` cannot be converted into `AdmissionRequest` pub struct ConvertConversionReviewError; -/// Struct that describes both request and response. +/// Struct that describes both request and response #[derive(Serialize, Deserialize)] pub struct ConversionReview { - /// Contains the API version and type of the request. + /// Contains the API version and type of the request #[serde(flatten)] pub types: TypeMeta, - /// Contains conversion request. + /// Contains conversion request #[serde(skip_serializing_if = "Option::is_none")] pub request: Option, - /// Contains conversion response. + /// Contains conversion response #[serde(skip_serializing_if = "Option::is_none")] #[serde(default)] pub response: Option, @@ -30,8 +30,10 @@ pub struct ConversionReview { /// Part of ConversionReview which is set on input (i.e. generated by apiserver) #[derive(Serialize, Deserialize)] pub struct ConversionRequest { - /// Copied from the corresponding consructing [`ConversionReview`]. - /// This field is not part of the Kubernetes API, it's consumed only by `kube`. + /// [`TypeMeta`] of the [`ConversionReview`] this response was created from + /// + /// This field dopied from the corresponding [`ConversionReview`]. + /// It is not part of the Kubernetes API, it's consumed only by `kube`. #[serde(skip)] pub types: Option, /// Random uid uniquely identifying this conversion call @@ -39,16 +41,16 @@ pub struct ConversionRequest { /// The API group and version the objects should be converted to #[serde(rename = "desiredAPIVersion")] pub desired_api_version: String, - /// The list of objects to convert. - /// May contain one or more objects, in one or more versions. - // This field used raw Value instead of Object/DynamicObject to simplify + /// The list of objects to convert + /// + /// Note that list may contain one or more objects, in one or more versions. + // This field uses raw Value instead of Object/DynamicObject to simplify // further downcasting. pub objects: Vec, } impl ConversionRequest { - /// Extracts request from the [`ConversionReview`]. - /// Fails if review has missing request. + /// Extracts request from the [`ConversionReview`] pub fn from_review(review: ConversionReview) -> Result { match review.request { Some(mut req) => { @@ -71,26 +73,32 @@ impl TryFrom for ConversionRequest { /// Part of ConversionReview which is set on output (i.e. generated by conversion webhook) #[derive(Serialize, Deserialize)] pub struct ConversionResponse { - /// Copied from the corresponding consructing [`ConversionRequest`]. - /// This field is not part of the Kubernetes API, it's consumed only by `kube`. + /// [`TypeMeta`] of the [`ConversionReview`] this response was derived from + /// + /// This field is copied from the corresponding [`ConversionRequest`]. + /// It is not part of the Kubernetes API, it's consumed only by `kube`. #[serde(skip)] pub types: Option, /// Copy of .request.uid pub uid: String, - /// Outcome of the conversion operation. + /// Outcome of the conversion operation + /// /// Success: all objects were successfully converted /// Failure: at least one object could not be converted. /// It is recommended that conversion fails as rare as possible. pub result: Status, - /// Converted objects in the same order as in the request. Should be empty - /// if conversion failed. + /// Converted objects + /// + /// This field should contain objects in the same order as in the request + /// Should be empty if conversion failed. #[serde(rename = "convertedObjects")] #[serde(skip_serializing_if = "Option::is_none")] pub converted_objects: Option>, } impl ConversionResponse { - /// Creates a new response, matching provided request. + /// Creates a new response, matching provided request + /// /// Returned response is empty: you should call `success` or `error` /// to get a complete `ConversionResponse`. pub fn for_request(request: ConversionRequest) -> Self { @@ -108,7 +116,8 @@ impl ConversionResponse { } } - /// Creates successful conversion response. + /// Creates successful conversion response + /// /// `converted_objects` must specify objects in the exact same order as on input. pub fn success(mut self, converted_objects: Vec) -> Self { self.result = Status::success(); @@ -116,7 +125,8 @@ impl ConversionResponse { self } - /// Creates failed conversion response (discouraged). + /// Creates failed conversion response (discouraged) + /// /// `request_uid` must be equal to the `.uid` field in the request. /// `message` and `reason` will be returned to the apiserver. pub fn error(mut self, message: &str, reason: &str) -> Self { @@ -124,7 +134,8 @@ impl ConversionResponse { self } - /// Creates failed conversion response, not matched with any request. + /// Creates failed conversion response, not matched with any request + /// /// You should only call this function when request couldn't be parsed into [`ConversionRequest`]. /// Otherwise use `error`. pub fn unmatched_error(message: &str, reason: &str) -> Self { @@ -136,7 +147,7 @@ impl ConversionResponse { } } - /// Converts response into a [`ConversionReview`] value, ready to be sent as a response. + /// Converts response into a [`ConversionReview`] value, ready to be sent as a response pub fn into_review(mut self) -> ConversionReview { ConversionReview { types: self.types.take().unwrap_or_else(|| {