From fde9a03c39ef5cf1042cf98df267d9b9c2e96c8a Mon Sep 17 00:00:00 2001 From: clux Date: Sun, 21 Nov 2021 23:21:51 +0000 Subject: [PATCH 1/2] purge last missing_docs allows + fix docs errors Signed-off-by: clux --- kube-client/src/client/auth/mod.rs | 4 +- kube-client/src/config/file_config.rs | 16 +++++++- kube-client/src/error.rs | 15 +++++-- kube-core/src/response.rs | 57 +++++++++++++++++++++++---- kube-runtime/src/wait.rs | 2 +- 5 files changed, 80 insertions(+), 14 deletions(-) diff --git a/kube-client/src/client/auth/mod.rs b/kube-client/src/client/auth/mod.rs index a14c5839a..d290c4ba0 100644 --- a/kube-client/src/client/auth/mod.rs +++ b/kube-client/src/client/auth/mod.rs @@ -41,10 +41,12 @@ pub enum Error { /// Failed to run auth exec command #[error("auth exec command '{cmd}' failed with status {status}: {out:?}")] - #[allow(missing_docs)] AuthExecRun { + /// The failed command cmd: String, + /// The exit status or exit code of the failed command status: std::process::ExitStatus, + /// Stdout/Stderr of the failed command out: std::process::Output, }, diff --git a/kube-client/src/config/file_config.rs b/kube-client/src/config/file_config.rs index bf9434b0a..6db8e4adb 100644 --- a/kube-client/src/config/file_config.rs +++ b/kube-client/src/config/file_config.rs @@ -1,4 +1,3 @@ -#![allow(missing_docs)] use std::{ collections::HashMap, fs, @@ -40,8 +39,10 @@ pub struct Kubeconfig { pub extensions: Option>, // legacy fields TODO: remove + /// Legacy field from TypeMeta #[serde(skip_serializing_if = "Option::is_none")] pub kind: Option, + /// Legacy field from TypeMeta #[serde(rename = "apiVersion")] #[serde(skip_serializing_if = "Option::is_none")] pub api_version: Option, @@ -51,8 +52,10 @@ pub struct Kubeconfig { #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(test, derive(PartialEq))] pub struct Preferences { + /// Enable colors #[serde(skip_serializing_if = "Option::is_none")] pub colors: Option, + /// Extensions holds additional information. This is useful for extenders so that reads and writes don't clobber unknown fields. #[serde(skip_serializing_if = "Option::is_none")] pub extensions: Option>, } @@ -61,7 +64,9 @@ pub struct Preferences { #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(test, derive(PartialEq))] pub struct NamedExtension { + /// Name of extension pub name: String, + /// Additional information for extenders so that reads and writes don't clobber unknown fields pub extension: serde_json::Value, } @@ -69,7 +74,9 @@ pub struct NamedExtension { #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(test, derive(PartialEq))] pub struct NamedCluster { + /// Name of cluster pub name: String, + /// Information about how to communicate with a kubernetes cluster pub cluster: Cluster, } @@ -79,6 +86,7 @@ pub struct NamedCluster { pub struct Cluster { /// The address of the kubernetes cluster (https://hostname:port). pub server: String, + /// Skips the validity check for the server's certificate. This will make your HTTPS connections insecure. #[serde(rename = "insecure-skip-tls-verify")] #[serde(skip_serializing_if = "Option::is_none")] pub insecure_skip_tls_verify: Option, @@ -103,7 +111,9 @@ pub struct Cluster { #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(test, derive(PartialEq))] pub struct NamedAuthInfo { + /// Name of the user pub name: String, + /// Information that describes identity of the user #[serde(rename = "user")] pub auth_info: AuthInfo, } @@ -168,7 +178,9 @@ pub struct AuthInfo { #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(test, derive(PartialEq))] pub struct AuthProviderConfig { + /// Name of the auth provider pub name: String, + /// Auth provider configuration pub config: HashMap, } @@ -198,7 +210,9 @@ pub struct ExecConfig { #[derive(Clone, Debug, Serialize, Deserialize)] #[cfg_attr(test, derive(PartialEq))] pub struct NamedContext { + /// Name of the context pub name: String, + /// Associations for the context pub context: Context, } diff --git a/kube-client/src/error.rs b/kube-client/src/error.rs index d2df017fe..cdb40b983 100644 --- a/kube-client/src/error.rs +++ b/kube-client/src/error.rs @@ -65,7 +65,7 @@ pub enum Error { /// Errors from Native TLS #[cfg(feature = "native-tls")] - #[cfg_attr(docsrs, doc(feature = "native-tls"))] + #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))] #[error("native tls error: {0}")] NativeTls(#[source] crate::client::NativeTlsError), @@ -89,18 +89,25 @@ pub enum Error { } #[derive(Error, Debug)] -// Redundant with the error messages and machine names -#[allow(missing_docs)] /// Possible errors when using API discovery pub enum DiscoveryError { + /// Invalid GroupVersion #[error("Invalid GroupVersion: {0}")] InvalidGroupVersion(String), + + /// Missing Kind #[error("Missing Kind: {0}")] MissingKind(String), + + /// Missing ApiGroup #[error("Missing Api Group: {0}")] MissingApiGroup(String), - #[error("Missing MissingResource: {0}")] + + /// MissingResource + #[error("Missing Resource: {0}")] MissingResource(String), + + /// Empty ApiGroup #[error("Empty Api Group: {0}")] EmptyApiGroup(String), } diff --git a/kube-core/src/response.rs b/kube-core/src/response.rs index daea3ce2b..303eb8182 100644 --- a/kube-core/src/response.rs +++ b/kube-core/src/response.rs @@ -1,51 +1,94 @@ //! Generic api response types use serde::Deserialize; -// TODO: replace with Status in k8s openapi? + /// A Kubernetes status object +/// +/// Equivalent to Status in k8s-openapi except we have have simplified options #[allow(missing_docs)] #[derive(Deserialize, Debug)] pub struct Status { - // TODO: typemeta - // TODO: metadata that can be completely empty (listmeta...) + /// Suggested HTTP return code (0 if unset) + #[serde(default, skip_serializing_if = "num::Zero::is_zero")] + pub code: u16, + + /// Status of the operation + /// + /// One of: `Success` or `Failure` - [more info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) #[serde(default, skip_serializing_if = "String::is_empty")] pub status: String, + + /// A human-readable description of the status of this operation #[serde(default, skip_serializing_if = "String::is_empty")] pub message: String, + + /// A machine-readable description of why this operation is in the “Failure” status. + /// + /// If this value is empty there is no information available. + /// A Reason clarifies an HTTP status code but does not override it. #[serde(default, skip_serializing_if = "String::is_empty")] pub reason: String, + + /// Extended data associated with the reason. + /// + /// Each reason may define its own extended details. + /// This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. #[serde(default, skip_serializing_if = "Option::is_none")] pub details: Option, - #[serde(default, skip_serializing_if = "num::Zero::is_zero")] - pub code: u16, } /// Status details object on the [`Status`] object #[derive(Deserialize, Debug)] #[serde(rename_all = "camelCase")] -#[allow(missing_docs)] pub struct StatusDetails { + /// The name attribute of the resource associated with the status StatusReason (when there is a single name which can be described) #[serde(default, skip_serializing_if = "String::is_empty")] pub name: String, + + /// The group attribute of the resource associated with the status StatusReason #[serde(default, skip_serializing_if = "String::is_empty")] pub group: String, + + /// The kind attribute of the resource associated with the status StatusReason + /// + /// On some operations may differ from the requested resource Kind - [more info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) #[serde(default, skip_serializing_if = "String::is_empty")] pub kind: String, + + /// UID of the resource (when there is a single resource which can be described) + /// + /// [More info](http://kubernetes.io/docs/user-guide/identifiers#uids) #[serde(default, skip_serializing_if = "String::is_empty")] pub uid: String, + + /// The Causes vector includes more details associated with the failure + /// + /// Not all StatusReasons may provide detailed causes. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub causes: Vec, + + /// If specified, the time in seconds before the operation should be retried. + /// + /// Some errors may indicate the client must take an alternate action - + /// for those errors this field may indicate how long to wait before taking the alternate action. #[serde(default, skip_serializing_if = "num::Zero::is_zero")] pub retry_after_seconds: u32, } /// Status cause object on the [`StatusDetails`] object #[derive(Deserialize, Debug)] -#[allow(missing_docs)] pub struct StatusCause { + /// A machine-readable description of the cause of the error. If this value is empty there is no information available. #[serde(default, skip_serializing_if = "String::is_empty")] pub reason: String, + + /// A human-readable description of the cause of the error. This field may be presented as-is to a reader. #[serde(default, skip_serializing_if = "String::is_empty")] pub message: String, + + /// The field of the resource that has caused this error, as named by its JSON serialization + /// + /// May include dot and postfix notation for nested attributes. Arrays are zero-indexed. + /// Fields may appear more than once in an array of causes due to fields having multiple errors. #[serde(default, skip_serializing_if = "String::is_empty")] pub field: String, } diff --git a/kube-runtime/src/wait.rs b/kube-runtime/src/wait.rs index 5f40a7470..363715a71 100644 --- a/kube-runtime/src/wait.rs +++ b/kube-runtime/src/wait.rs @@ -247,7 +247,7 @@ pub mod delete { /// /// # Errors /// - /// Returns an [`Error`] if the object was unable to be deleted, or if the wait was interrupted. + /// Returns an [`Error`](enum@super::Error) if the object was unable to be deleted, or if the wait was interrupted. #[allow(clippy::module_name_repetitions)] pub async fn delete_and_finalize( api: Api, From 43db9b9a327780d2071a7f95f70bd497e545ab47 Mon Sep 17 00:00:00 2001 From: kazk Date: Sun, 21 Nov 2021 16:42:00 -0800 Subject: [PATCH 2/2] Remove `#[allow(missing_docs)]` Signed-off-by: kazk --- kube-core/src/response.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/kube-core/src/response.rs b/kube-core/src/response.rs index 303eb8182..cb55640b6 100644 --- a/kube-core/src/response.rs +++ b/kube-core/src/response.rs @@ -4,7 +4,6 @@ use serde::Deserialize; /// A Kubernetes status object /// /// Equivalent to Status in k8s-openapi except we have have simplified options -#[allow(missing_docs)] #[derive(Deserialize, Debug)] pub struct Status { /// Suggested HTTP return code (0 if unset)