docs: crate

Author: codinaut

src/lib.rs

@@ -1,7 +1,36 @@
+//! Test kit for logics which involves environment variables.
+//!
+//! # Usage
+//!
+//! To test environment-related logics:
+//! ```
+//! use envtestkit::set_env;
+//! use envtestkit::lock::lock_read;
+//! use std::ffi::OsString;
+//!
+//! let _lock = lock_test();
+//! let _test = set_env(OsString::from("ENV_KEY"), "value");
+//! // Do your test here ...
+//! ```
+//!
+//! Complete examples can be found in `examples/` directory of this crate.
+//!
+//! # Race Condition
+//!
+//! Environment variables are global states. These things need to be ensured for building robust tests:
+//! - Run environment-modifying tests in serial.
+//! - Run environment-sensitive tests while no environment-modifying tests are running at the moment.
+//!
+//! For that, please use appropriate locks in your tests. See the [lock](lock/index.html) module.
+
+#![warn(missing_docs)]
+#![warn(missing_doc_code_examples)]
+
 #[cfg(feature = "lock")]
 #[macro_use]
 extern crate lazy_static;
 
+/// Tools for serializing environment-modifying tests.
 #[cfg(feature = "lock")]
 pub mod lock;
 

src/lock.rs

@@ -6,10 +6,32 @@ lazy_static! {
     static ref LOCK: RwLock<()> = RwLock::new(());
 }
 
+/// Ensure no environment-modifying tests are running at the moment.
+///
+/// This method should be called before running environment-sensitive tests.
+///
+/// # Examples
+///
+/// ```
+/// use envtestkit::lock::lock_read;
+///
+/// let _lock = lock_read();
+/// ```
 pub fn lock_read<'a>() -> RwLockReadGuard<'a, RawRwLock, ()> {
     LOCK.read()
 }
 
+/// Serialize environment-modifying tests.
+///
+/// This method should be called before running environment-modifying tests.
+///
+/// # Examples
+///
+/// ```
+/// use envtestkit::lock::lock_test;
+///
+/// let _lock = lock_test();
+/// ```
 pub fn lock_test<'a>() -> RwLockWriteGuard<'a, RawRwLock, ()> {
     LOCK.write()
 }

src/testkit.rs

@@ -1,12 +1,25 @@
 use std::env;
 use std::ffi::{OsStr, OsString};
 
+/// Guard temporary environment modification.
+///
+/// Clean up environment modification after this guard is out of scope.
 #[must_use = "if unused environment will immediately be cleaned up"]
 pub struct EnvironmentTestGuard {
     key: OsString,
     value: Option<OsString>,
 }
 
+/// Set environment variable temporarily for testing.
+///
+/// # Examples
+///
+/// ```
+/// use envtestkit::set_env;
+/// use std::ffi::OsString;
+///
+/// let _test = set_env(OsString::from("ENV_KEY"), "value");
+/// ```
 pub fn set_env<V: AsRef<OsStr>>(key: OsString, value: V) -> EnvironmentTestGuard {
     let prev_value = env::var_os(&key);
     env::set_var(&key, value);