Add docstrings

Author: ynqa

src/client/mod.rs

@@ -6,6 +6,7 @@ use serde::de::DeserializeOwned;
 
 use super::config::Configuration;
 
+/// APIClient requires `config::Configuration` includes client to connect with kubernetes cluster.
 pub struct APIClient {
     configuration: Rc<Configuration>,
 }
@@ -16,6 +17,7 @@ impl APIClient {
         APIClient { configuration: rc }
     }
 
+    /// Returns kubernetes resources binded `Arnavion/k8s-openapi-codegen` APIs.
     pub fn request<T>(&self, request: http::Request<Vec<u8>>) -> Result<T, Error>
     where
         T: DeserializeOwned,

src/config/apis.rs

@@ -6,6 +6,7 @@ use serde_yaml;
 
 use config::utils;
 
+/// Config stores information to connect remote kubernetes cluster.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Config {
     pub kind: Option<String>,
@@ -21,24 +22,28 @@ pub struct Config {
     pub extensions: Option<Vec<NamedExtension>>,
 }
 
+/// Preferences stores extensions for cli.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Preferences {
     pub colors: Option<bool>,
     pub extensions: Option<Vec<NamedExtension>>,
 }
 
+/// NamedExtention associates name with extension.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct NamedExtension {
     pub name: String,
     pub extension: String,
 }
 
+/// NamedCluster associates name with cluster.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct NamedCluster {
     pub name: String,
     pub cluster: Cluster,
 }
 
+/// Cluster stores information to connect kubernetes cluster.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Cluster {
     pub server: String,
@@ -50,13 +55,15 @@ pub struct Cluster {
     pub certificate_authority_data: Option<String>,
 }
 
+/// NamedAuthInfo associates name with authentication.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct NamedAuthInfo {
     pub name: String,
     #[serde(rename = "user")]
     pub auth_info: AuthInfo,
 }
 
+/// AuthInfo stores information to tell cluster who you are.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct AuthInfo {
     pub username: Option<String>,
@@ -82,12 +89,14 @@ pub struct AuthInfo {
     pub impersonate_groups: Option<Vec<String>>,
 }
 
+/// NamedContext associates name with context.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct NamedContext {
     pub name: String,
     pub context: Context,
 }
 
+/// Context stores tuple of cluster and user information.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Context {
     pub cluster: String,

src/config/incluster_config.rs

@@ -10,6 +10,7 @@ pub const SERVICE_PORTENV: &str = "KUBERNETES_SERVICE_PORT";
 const SERVICE_TOKENFILE: &str = "/var/run/secrets/kubernetes.io/serviceaccount/token";
 const SERVICE_CERTFILE: &str = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt";
 
+/// Returns kubernetes address from specified environment variables.
 pub fn kube_server() -> Option<String> {
     let f = |(h, p)| format!("https://{}:{}", h, p);
     kube_host().and_then(|h| kube_port().map(|p| f((h, p))))
@@ -23,10 +24,12 @@ fn kube_port() -> Option<String> {
     env::var(SERVICE_PORTENV).ok()
 }
 
+/// Returns token from specified path in cluster.
 pub fn load_token() -> Result<String, Error> {
     utils::data_or_file(&None, &Some(SERVICE_TOKENFILE.to_string()))
 }
 
+/// Returns certification from specified path in cluster.
 pub fn load_cert() -> Result<X509, Error> {
     let ca = utils::data_or_file_with_base64(&None, &Some(SERVICE_CERTFILE.to_string()))?;
     X509::from_pem(&ca).map_err(Error::from)

src/config/kube_config.rs

@@ -7,6 +7,7 @@ use openssl::x509::X509;
 
 use config::apis::{AuthInfo, Cluster, Config, Context};
 
+/// KubeConfigLoader loads current context, cluster, and authentication information.
 #[derive(Debug)]
 pub struct KubeConfigLoader {
     pub current_context: Context,

src/config/mod.rs

@@ -9,6 +9,7 @@ use reqwest::{header, Certificate, Client, Identity};
 
 use self::kube_config::KubeConfigLoader;
 
+/// Configuration stores kubernetes path and client for requests.
 pub struct Configuration {
     pub base_path: String,
     pub client: Client,
@@ -23,6 +24,15 @@ impl Configuration {
     }
 }
 
+/// Returns a config includes authentication and cluster infomation from kubeconfig file.
+///
+/// # Example
+/// ```
+/// use kubernetes::config;
+///
+/// let kubeconfig = config::load_kube_config()
+///     .expect("failed to load kubeconfig");
+/// ```
 pub fn load_kube_config() -> Result<Configuration, Error> {
     let kubeconfig = utils::kubeconfig_path()
         .or_else(utils::default_kube_path)
@@ -69,6 +79,16 @@ pub fn load_kube_config() -> Result<Configuration, Error> {
     ))
 }
 
+/// Returns a config which is used by clients within pods on kubernetes.
+/// It will return an error if called from out of kubernetes cluster.
+///
+/// # Example
+/// ```
+/// use kubernetes::config;
+///
+/// let kubeconfig = config::incluster_config()
+///     .expect("failed to load incluster config");
+/// ```
 pub fn incluster_config() -> Result<Configuration, Error> {
     let server = incluster_config::kube_server().ok_or(format_err!(
         "Unable to load incluster config, {} and {} must be defined",

src/config/utils.rs

@@ -9,10 +9,12 @@ use failure::Error;
 
 const KUBECONFIG: &str = "KUBECONFIG";
 
+/// Returns kubeconfig path from specified environment variable.
 pub fn kubeconfig_path() -> Option<PathBuf> {
     env::var_os(KUBECONFIG).map(PathBuf::from)
 }
 
+/// Returns kubeconfig path from `$HOME/.kube/config`.
 pub fn default_kube_path() -> Option<PathBuf> {
     home_dir().map(|h| h.join(".kube").join("config"))
 }