chore: add documentation for env string

itconfig/src/envstr.rs

@@ -1,20 +1,46 @@
 use std::ops::Deref;
 
-#[doc(hidden)]
+/// A trait for converting value to EnvString.
+///
+/// This trait automatically implemented for any type which implements the
+/// [`Display`] trait. As such, `ToEnvString` shouldn't be implemented directly:
+/// [`Display`] should be implemented instead, and you get the `ToEnvString`
+/// implementation for free.
+///
+/// [`Display`]: std::fmt::Display
 pub trait ToEnvString {
+    /// Converts the giving value to a `EnvString`.
+    ///
+    /// # Examples
+    ///
+    /// basic usage
+    ///
+    /// ```rust
+    /// # use itconfig::{EnvString, ToEnvString};
+    /// let i = 5;
+    /// let five = EnvString::from("5");
+    /// assert_eq!(five, i.to_env_string());
+    /// ```
     fn to_env_string(&self) -> EnvString;
 }
 
-#[doc(hidden)]
+/// Simple and safe type conversions that may fail in a controlled way under
+/// some circumstances.
+///
+/// This trait automatically implemented for all standard primitives. If you
+/// want to use your custom type in the library you need to implement
+/// `ToEnvString` and `FromEnvString` manually.
 pub trait FromEnvString: Sized {
+    /// The type returned in the event of a conversion error.
     type Err;
 
+    /// Performs the conversion.
     fn from_env_string(s: &EnvString) -> Result<Self, Self::Err>;
 }
 
 impl<T> ToEnvString for T
 where
-    T: ToString,
+    T: std::fmt::Display,
 {
     #[inline]
     fn to_env_string(&self) -> EnvString {
@@ -68,6 +94,7 @@ impl FromEnvString for bool {
     }
 }
 
+#[doc(hidden)]
 #[cfg(feature = "array")]
 #[derive(Debug)]
 pub enum ArrayEnvError {
@@ -90,8 +117,7 @@ where
             .and_then(|vec| {
                 vec.iter()
                     .map(|v| {
-                        v.to_env_string()
-                            .parse::<T>()
+                        FromEnvString::from_env_string(&v.to_env_string())
                             .map_err(|_| ArrayEnvError::FailedToParse)
                     })
                     .collect::<Result<Vec<T>, _>>()
@@ -115,13 +141,20 @@ impl FromEnvString for &'static str {
     }
 }
 
-#[doc(hidden)]
+/// Wrapper under String type.
+///
+/// When we read the environment variable, we automatically convert the value
+/// to EnvString and then convert it to your expected type.
+///
 #[derive(Debug, PartialEq, Clone)]
 pub struct EnvString(String);
 
-impl EnvString {
-    pub fn parse<T: FromEnvString>(&self) -> Result<T, T::Err> {
-        FromEnvString::from_env_string(self)
+impl<T> From<T> for EnvString
+where
+    T: ToEnvString,
+{
+    fn from(val: T) -> Self {
+        val.to_env_string()
     }
 }
 

itconfig/src/error.rs

@@ -1,9 +1,13 @@
 use std::error;
 use std::fmt;
 
+/// The error type for operations interacting with environment variables
 #[derive(Debug, PartialEq)]
 pub enum EnvError {
+    /// The specified environment variable was not present in the current process's environment.
     MissingVariable(String),
+
+    /// Failed to parse the specified environment variable.
     FailedToParse(String),
 }
 

itconfig/src/getenv.rs

@@ -1,4 +1,5 @@
-use crate::prelude::*;
+use crate::envstr::*;
+use crate::error::*;
 use std::env;
 
 /// This function is similar as `get_env`, but it unwraps result with panic on error.
@@ -123,17 +124,14 @@ where
         .and_then(|env_str| parse_env_variable(env_name, env_str))
 }
 
-#[doc(hidden)]
 fn parse_env_variable<T>(env_name: &str, env_str: EnvString) -> Result<T, EnvError>
 where
     T: FromEnvString,
 {
-    env_str
-        .parse::<T>()
+    FromEnvString::from_env_string(&env_str)
         .map_err(|_| EnvError::FailedToParse(env_name.to_string()))
 }
 
-#[doc(hidden)]
 fn make_panic<T>(e: EnvError) -> T {
     panic!("{}", e)
 }

itconfig/src/lib.rs

@@ -140,6 +140,7 @@
 #![forbid(unsafe_code)]
 #![deny(
     missing_debug_implementations,
+    missing_docs,
     unstable_features,
     unused_imports,
     unused_qualifications
@@ -149,18 +150,14 @@
 
 /////////////////////////////////////////////////////////////////////////////
 
-pub mod envstr;
+mod envstr;
 mod error;
 mod getenv;
 
+pub use self::envstr::*;
 pub use self::error::*;
 pub use self::getenv::*;
 
-pub mod prelude {
-    pub use crate::envstr::*;
-    pub use crate::error::*;
-}
-
 #[cfg(feature = "macro")]
 extern crate itconfig_macro;
 #[cfg(feature = "macro")]