Add some documentation

README.adoc

@@ -10,8 +10,7 @@ image:https://img.shields.io/crates/l/serial_test.svg[MIT license,link={url-repo
 image:{url-repo}/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-repo}/actions]
 endif::[]
 
-
-A crate to deal with environment variable changes specially during tests.
+`temp_env_vars` allows to to manipulate enviornment variables during a test and reset all changes when the test is done.
 
 [CAUTION]
 ====
@@ -34,9 +33,21 @@ temp_env_vars_core = { git = "https://github.com/guenhter/temp_env_vars.git", br
 
 == Usage
 
-Use with `#[temp_env_vars]`
+`temp_env_vars` can be used in two different forms:
+
+. as macro `#[temp_env_vars]`
+. with `TestEnvScope::new()`
+
+
+=== Use as macro
 
-```Rust
+`#[temp_env_vars]` is the preferred way to use the `temp_env_vars` crate.
+Every change to envionrment variables within the execution of the test function
+will be reset after the test has ended.
+
+If more tests are used with this macro, those tests will be executed sequentially to avoid an enviornment variable mixup.
+
+```rust
 #[test]
 #[temp_env_vars]
 fn test_some() {
@@ -48,9 +59,13 @@ fn test_some() {
 ```
 
 
-Use with `TestEnvScope`
+=== Use with TestEnvScope
+
+If resetting the environment variables after the test execution is not sufficient, but the reset must happen somewhere within the test, the `TestEnvScope` can be used to have better control.
+
+Whenever the created `TestEnvScope` goes out of scope, all env vars are reset.
 
-```Rust
+```rust
 #[test]
 #[serial] // Advices to use serial, alse parallel tests could mix up envs
 fn test_some() {

src/lib.rs

@@ -1,3 +1,68 @@
+//! # temp_env_vars
+//!
+//! `temp_env_vars` allows to to manipulate enviornment variables during a test and reset
+//!  all changes when the test is done.
+//!
+//! ## Usage
+//!
+//! `temp_env_vars` can be used in two different forms:
+//!
+//! 1. as macro `#[temp_env_vars]`
+//! 2. with `TestEnvScope::new()`
+//!
+//! ### Use as macro
+//!
+//! `#[temp_env_vars]` is the preferred way to use the `temp_env_vars` crate.
+//! Every change to envionrment variables within the execution of the test function
+//! will be reset after the test has ended.
+//!
+//! If more tests are used with this macro, those tests will be executed sequentially
+//! to avoid an enviornment variable mixup.
+//!
+//! ```rust
+//! #[test]
+//! #[temp_env_vars]
+//! fn test_some() {
+//!     std::env::set_var("FOO", "BAR");
+//!     assert_eq!(std::env::var("FOO").unwrap(), "BAR");
+//!
+//!     // Env vars get reset when test is done
+//! }
+//! ```
+//!
+//! ### Use with TestEnvScope
+//!
+//!
+//! If resetting the environment variables after the test execution is not sufficient,
+//! but the reset must happen somewhere within the test, the `TestEnvScope` can be
+//! used to have better control.
+//!
+//! Whenever the created `TestEnvScope` goes out of scope, all env vars are reset.
+//!
+//! ```rust
+//! #[test]
+//! #[serial] // Advices to use serial, alse parallel tests could mix up envs
+//! fn test_some() {
+//!     let _env_scope = TestEnvScope::new();
+//!     std::env::set_var("FOO", "BAR");
+//!     assert_eq!(std::env::var("FOO").unwrap(), "BAR");
+//!
+//!     // After "_env_scope" goes out of scope, all vars are restored
+//! }
+//!
+//! #[test]
+//! #[serial] // Advices to use serial, alse parallel tests could mix up envs
+//! fn test_bar() {
+//!     let _env_scope = TestEnvScope::new();
+//!     std::env::set_var("FOO", "BAR");
+//!     assert_eq!(std::env::var("FOO").unwrap(), "BAR");
+//!
+//!     drop(_env_scope); // After "_env_scope" goes out of scope, all vars are restored
+//!
+//!
+//!     // "FOO" is not longer set here.
+//! }
+//! ```
 pub use temp_env_vars_core::TestEnvScope;
 pub use temp_env_vars_macro::temp_env_vars;
 
@@ -10,7 +75,7 @@ mod test {
     use temp_env_vars_core::TestEnvScope;
 
     #[test]
-    #[serial] // Advised to use serial_test if other env-tests are not used with annotated with "temp_env_vars"
+    #[serial] // Advised to use serial_test if other env-tests are not used with annotated with "temp_env_vars
     #[temp_env_vars]
     fn test_with_macro() {
         assert_that!(std::env::var("FOO")).is_err();

temp_env_vars_core/src/lib.rs

@@ -1,10 +1,51 @@
+//! # temp_env_vars_core
+//!
+//! `temp_env_vars_core` allows to to manipulate enviornment variables during a test
+//! and reset all changes when the test is done.
+//!
+//! ## Usage
+//!
+//! If resetting the env vars when the test completes is sufficient, the macro form
+//! `#[temp_env_vars]` is recommended over this crate.
+//!
+//! If resetting the environment variables after the test execution is not sufficient,
+//! but the reset must happen somewhere within the test, the `TestEnvScope` can be
+//! used to have better control.
+//!
+//! Whenever the created `TestEnvScope` goes out of scope, all env vars are reset.
+//!
+//! ```rust
+//! #[test]
+//! #[serial] // Advices to use serial, alse parallel tests could mix up envs
+//! fn test_some() {
+//!     let _env_scope = TestEnvScope::new();
+//!     std::env::set_var("FOO", "BAR");
+//!     assert_eq!(std::env::var("FOO").unwrap(), "BAR");
+//!
+//!     // After "_env_scope" goes out of scope, all vars are restored
+//! }
+//!
+//! #[test]
+//! #[serial] // Advices to use serial, alse parallel tests could mix up envs
+//! fn test_bar() {
+//!     let _env_scope = TestEnvScope::new();
+//!     std::env::set_var("FOO", "BAR");
+//!     assert_eq!(std::env::var("FOO").unwrap(), "BAR");
+//!
+//!     drop(_env_scope); // After "_env_scope" goes out of scope, all vars are restored
+//!
+//!
+//!     // "FOO" is not longer set here.
+//! }
+//! ```
 use std::{
     collections::HashMap,
     sync::{Arc, LazyLock, Mutex},
 };
 
 // Makes the mutex available for the `temp_env_vars` macro. Unfortunately, Macro traits cannot
 // export other types than macros, so this is the least bad place to export this then.
+#[doc(hidden)]
 pub static TEMP_ENV_VAR_MACRO_MUTEX: LazyLock<Arc<Mutex<()>>> = LazyLock::new(Arc::default);
 
 pub struct TestEnvScope {