update docs

Author: tao-guo

README.md

@@ -115,10 +115,14 @@ eprintln!("There are {} words in above sentence", n);
 ```
 
 #### Abstraction without overhead
+
 Since all the macros' lexical analysis and syntactic analysis happen at compile time, it can
 basically generate code the same as calling `std::process` APIs manually. It also includes
 command type checking, so most of the errors can be found at compile time instead of at
-runtime.
+runtime. With tools like `rust-analyzer`, it can give you real-time feedback for broken
+commands being used.
+
+You can use `cargo expand` to check the generated code.
 
 #### Intuitive parameters passing
 When passing parameters to `run_cmd!` and `run_fun!` macros, if they are not part to rust
@@ -160,6 +164,23 @@ for opts in gopts {
 Right now piping and stdin, stdout, stderr redirection are supported. Most parts are the same as in
 [bash scripts](https://www.gnu.org/software/bash/manual/html_node/Redirections.html#Redirections).
 
+#### logging
+
+This library provides convenient macros and builtin commands for logging. It also automatically logs
+command execution failures, along with messages which were printed to stderr originally.
+
+```rust
+let dir: &str = "folder with spaces";
+assert!(run_cmd!(mkdir /tmp/$dir; ls /tmp/$dir).is_ok());
+assert!(run_cmd!(mkdir /tmp/"$dir"; ls /tmp/"$dir"; rmdir /tmp/"$dir").is_err());
+// output:
+// INFO - mkdir: cannot create directory ‘/tmp/folder with spaces’: File exists
+// ERROR - Running ["mkdir", "/tmp/folder with spaces"] failed, Error: ["mkdir", "/tmp/folder with spaces"] exited with error; status code: 1
+```
+
+It is using rust [log crate](https://crates.io/crates/log), and you can use your actual favorite logging
+implementation.
+
 #### Builtin commands
 ##### cd
 cd: set process current directory, which is always enabled

src/lib.rs

@@ -126,10 +126,14 @@
 //! ```
 //!
 //! ### Abstraction without overhead
+//!
 //! Since all the macros' lexical analysis and syntactic analysis happen at compile time, it can
 //! basically generate code the same as calling `std::process` APIs manually. It also includes
 //! command type checking, so most of the errors can be found at compile time instead of at
-//! runtime.
+//! runtime. With tools like `rust-analyzer`, it can give you real-time feedback for broken
+//! commands being used.
+//!
+//! You can use `cargo expand` to check the generated code.
 //!
 //! ### Intuitive parameters passing
 //! When passing parameters to `run_cmd!` and `run_fun!` macros, if they are not part to rust
@@ -177,6 +181,24 @@
 //! Right now piping and stdin, stdout, stderr redirection are supported. Most parts are the same as in
 //! [bash scripts](https://www.gnu.org/software/bash/manual/html_node/Redirections.html#Redirections).
 //!
+//! ### logging
+//!
+//! This library provides convenient macros and builtin commands for logging. It also automatically logs
+//! command execution failures, along with messages which were printed to stderr originally.
+//!
+//! ```no_run
+//! # use cmd_lib::*;
+//! let dir: &str = "folder with spaces";
+//! assert!(run_cmd!(mkdir /tmp/$dir; ls /tmp/$dir).is_ok());
+//! assert!(run_cmd!(mkdir /tmp/"$dir"; ls /tmp/"$dir"; rmdir /tmp/"$dir").is_err());
+//! // output:
+//! // INFO - mkdir: cannot create directory ‘/tmp/folder with spaces’: File exists
+//! // ERROR - Running ["mkdir", "/tmp/folder with spaces"] failed, Error: ["mkdir", "/tmp/folder with spaces"] exited with error; status code: 1
+//! ```
+//!
+//! It is using rust [log crate](https://crates.io/crates/log), and you can use your actual favorite logging
+//! implementation.
+//!
 //! ### Builtin commands
 //! #### cd
 //! cd: set process current directory, which is always enabled
@@ -302,7 +324,9 @@ pub use cmd_lib_macros::{
     cmd_debug, cmd_die, cmd_echo, cmd_error, cmd_info, cmd_trace, cmd_warn, export_cmd, run_cmd,
     run_fun, spawn, spawn_with_output, use_builtin_cmd, use_custom_cmd,
 };
+/// Return type for run_fun!() macro
 pub type FunResult = std::io::Result<String>;
+/// Return type for run_cmd!() macro
 pub type CmdResult = std::io::Result<()>;
 pub use builtins::{
     builtin_cat, builtin_debug, builtin_die, builtin_echo, builtin_error, builtin_info,

src/process.rs

@@ -13,7 +13,7 @@ use std::path::Path;
 use std::process::{Command, Stdio};
 use std::sync::Mutex;
 
-/// Process environment for builtin or custom commands
+/// Environment for builtin or custom commands
 pub struct CmdEnv {
     stdin: CmdIn,
     stdout: CmdOut,
@@ -23,26 +23,32 @@ pub struct CmdEnv {
     current_dir: String,
 }
 impl CmdEnv {
+    /// Returns the arguments for this command
     pub fn args(&self) -> &[String] {
         &self.args
     }
 
+    /// Fetches the environment variable key for this command
     pub fn var(&self, key: &str) -> Option<&String> {
         self.vars.get(key)
     }
 
+    /// Returns the current working directory for this command
     pub fn current_dir(&self) -> &str {
         &self.current_dir
     }
 
+    /// Returns a new handle to the standard input for this command
     pub fn stdin(&mut self) -> impl Read + '_ {
         &mut self.stdin
     }
 
+    /// Returns a new handle to the standard output for this command
     pub fn stdout(&mut self) -> impl Write + '_ {
         &mut self.stdout
     }
 
+    /// Returns a new handle to the standard error for this command
     pub fn stderr(&mut self) -> impl Write + '_ {
         &mut self.stderr
     }