improved documentation

Author: Canop

CHANGELOG.md

@@ -1,3 +1,7 @@
+<a name="v2.0.1"></a>
+### v2.0.1 - 2021-05-20
+Improved documentation
+
 <a name="v2.0.0"></a>
 ### v2.0.0 - 2021-05-17
 - regular expressions are now checked at compile time

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lazy-regex"
-version = "2.0.0"
+version = "2.0.1"
 authors = ["Canop <[email protected]>"]
 edition = "2018"
 description = "lazy static regular expressions checked at compile time"
@@ -17,7 +17,7 @@ regex = "1.5"
 [dependencies.proc_macros]
 package = "lazy-regex-proc_macros"
 path = "src/proc_macros"
-version = "2.0.0"
+version = "2.0.1"
 
 [workspace]
 members = ["src/proc_macros", "examples/regexes"]

README.md

@@ -75,16 +75,16 @@ assert_eq!(b, true);
 ```rust
 use lazy_regex::regex_find;
 
-let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.").unwrap();
-assert_eq!(f_word, "fox");
+let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.");
+assert_eq!(f_word, Some("fox"));
 ```
 
 # Capture
 
 ```rust
 use lazy_regex::regex_captures;
 
-let (_, letter) = regex_captures!(r#"([a-z])\d+"#i, "form A42").unwrap();
+let (_, letter) = regex_captures!("([a-z])[0-9]+"i, "form A42").unwrap();
 assert_eq!(letter, "A");
 
 let (whole, name, version) = regex_captures!(

src/lib.rs

@@ -4,10 +4,10 @@ Use the  [regex!] macro to build regexes:
 
 * they're checked at compile time
 * they're wrapped in `once_cell` lazy static initializers so that they're compiled only once
-* they can hold flags with a familiar suffix syntax: `let case_insensitive_regex = regex!("ab*"i);`
+* they can hold flags as suffix: `let case_insensitive_regex = regex!("ab*"i);`
 * regex creation is less verbose
 
-This macro builds normal instances of [regex::Regex] so all the usual features are available.
+This macro returns references to normal instances of [regex::Regex] so all the usual features are available.
 
 You may also use shortcut macros for testing a match or capturing groups as substrings:
 
@@ -58,16 +58,16 @@ assert_eq!(b, true);
 ```
 use lazy_regex::regex_find;
 
-let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.").unwrap();
-assert_eq!(f_word, "fox");
+let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.");
+assert_eq!(f_word, Some("fox"));
 ```
 
 # Capture
 
 ```
 use lazy_regex::regex_captures;
 
-let (_, letter) = regex_captures!(r#"([a-z])\d+"#i, "form A42").unwrap();
+let (_, letter) = regex_captures!("([a-z])[0-9]+"i, "form A42").unwrap();
 assert_eq!(letter, "A");
 
 let (whole, name, version) = regex_captures!(

src/proc_macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lazy-regex-proc_macros"
-version = "2.0.0"
+version = "2.0.1"
 authors = ["Canop <[email protected]>"]
 description = "proc macros for the lazy_regex crate"
 license = "MIT"

src/proc_macros/mod.rs

@@ -41,7 +41,7 @@ impl From<LitStr> for RegexCode {
             };
         }
 
-        // the next line is here to prevent compilation if the
+        // the next line prevents compilation if the
         // literal is invalid as a regular expression
         let regex = regex::Regex::new(&regex_string).unwrap();
 
@@ -76,6 +76,9 @@ pub fn regex(input: TokenStream) -> TokenStream {
     RegexCode::from(lit_str).build.into()
 }
 
+/// wrapping of the two arguments given to one of the
+/// `regex_is_match`, `regex_find`, or `regex_captures`
+/// macros.
 struct RegexAndExpr {
     regex_str: LitStr,
     value: Expr,
@@ -116,6 +119,14 @@ pub fn regex_is_match(input: TokenStream) -> TokenStream {
     q.into()
 }
 
+/// extract the leftmost match of the regex in the
+/// second argument, as a &str
+///
+/// Example:
+/// ```
+/// let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.");
+/// assert_eq!(f_word, Some("fox"));
+/// ```
 #[proc_macro]
 pub fn regex_find(input: TokenStream) -> TokenStream {
     let regex_and_expr_args = parse_macro_input!(input as RegexAndExpr);