Fix documentation links, typos, content

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "assertables"
-version = "8.2.0"
+version = "8.2.1"
 authors = ["Joel Parker Henderson <[email protected]>"]
 edition = "2021"
 description = "Assertables: Rust crate of macros `assert…!` for better tests, quality assurance, debug testing, and runtime reliability."
@@ -25,7 +25,7 @@ split-debuginfo = "packed"
 [dependencies]
 
 [dev-dependencies]
-cargo-dist = "0.22.0" # Cargo distribution builder for release engineering
-cargo-release = "0.25.10" # Cargo release automation
+cargo-dist = "0.22.1" # Cargo distribution builder for release engineering
+cargo-release = "0.25.11" # Cargo release automation
 regex = "1.10.6" # Regular expressions parser, compiler, and executer
 once_cell = "1.19.0" # Single assignment cells and lazy values

README.md

@@ -13,62 +13,91 @@ compile-time tests and run-time reliability.
 
 The Rust programming language provides a few built-in assert macros to test code:
 
-```rust
-assert!()
-assert_eq!(a, b)
-assert_ne!(a, b)
-```
+* `assert!()`
+* `assert_eq!(a, b)`
+* `assert_ne!(a, b)`
 
 The assertables crate provides many more, so you can write smarter tests.
 
 For values:
 
-```rust
-assert_gt!(a, b)
-assert_lt!(a, b)
-```
+* [`assert_gt!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_gt.html)
+* [`assert_lt!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_lt.html)
 
 For numbers:
 
-```rust
-assert_in_delta!(a, b, delta)
-assert_in_epsilon!(a, b, epsilon)
-```
+* [`assert_in_delta!(a, b, delta)`](https://docs.rs/assertables/latest/assertables/macro.assert_in_delta.html)
+* [`assert_in_epsilon!(a, b, epsilon)`](https://docs.rs/assertables/latest/assertables/macro.assert_in_epsilon.html)
 
 For strings:
 
-```rust
-assert_starts_with!(a, b)
-assert_ends_with!(a, b)
-```
+* [`assert_starts_with!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_starts_with.html)
+* [`assert_ends_with!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_ends_with.html)
 
 For matching:
 
-```rust
-assert_contains!(a, b)
-assert_is_match!(a, b)
-```
+* [`assert_contains!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_contains.html)
+* [`assert_is_match!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_is_match.html)
+
+For infix numeric operators and infix logical operators:
+
+* [`assert_infix!(a == b)`](https://docs.rs/assertables/latest/assertables/macro.assert_infix.html)
+* [`assert_infix!(a && b)`](https://docs.rs/assertables/latest/assertables/macro.assert_infix.html)
+
+For maybes:
+
+* [`assert_result_ok!(a)`](https://docs.rs/assertables/latest/assertables/macro.assert_result_ok.html)
+* [`assert_option_some!(a)`](macro@crate::assert_option_some)
 
 For collections such as arrays, vectors, maps, sets:
 
-```rust
-assert_set_subset!(a, b)
-assert_set_disjoint!(a, b)
-```
+* [`assert_set_subset_eq!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_set_subset_eq.html)
+* [`assert_set_disjoint_eq!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_set_disjoint_eq.html)
 
 For file system paths and input/output readers:
 
-```rust
-assert_fs_read_to_string_eq!(path1, path2)
-assert_io_read_to_string_eq!(reader1, reader2)
-```
+* [`assert_fs_read_to_string_eq!(path1, path2)`](https://docs.rs/assertables/latest/assertables/macro.assert_fs_read_to_string_eq.html)
+* [`assert_io_read_to_string_eq!(reader1, reader2)`](https://docs.rs/assertables/latest/assertables/macro.assert_io_read_to_string_eq.html)
 
 For command capture of standard output and standard error:
 
-```rust
-assert_command_stdout_eq!(command1 stdout = command2 stdout);
-assert_command_stderr_eq!(command1, command2);
-```
+* [`assert_command_stdout_eq!(command1, command2)`](https://docs.rs/assertables/latest/assertables/macro.assert_command_stdout_eq.html);
+* [`assert_program_args_stdout_eq!(program1, args1, program2, args2`](https://docs.rs/assertables/latest/assertables/macro.assert_program_args_stdout_eq.html)
+
+There are many more macros that are grouped into modules.
+
+Modules for enums:
+
+* [`assert_option`](https://docs.rs/assertables/latest/assertables/macro.assert_option.html)for `Option` {`Some`, `None`}
+
+* [`assert_result`](https://docs.rs/assertables/latest/assertables/macro.assert_result.html) for `Result` {`Ok`, `Err`}
+
+Modules for collections, such as arrays, vectors, lists, maps:
+
+* [`assert_set`](https://docs.rs/assertables/latest/assertables/macro.assert_set.html) for set collections
+
+* [`assert_bag`](https://docs.rs/assertables/latest/assertables/macro.assert_bag.html) for bag collections
+
+Modules for functions:
+
+* [`assert_fn`](https://docs.rs/assertables/latest/assertables/macro.assert_fn.html) for functions in general.
+
+* [`assert_fn_ok`](https://docs.rs/assertables/latest/assertables/macro.assert_ok.html) for functions that return `Result::Ok`.
+
+* [`assert_fn_err`](https://docs.rs/assertables/latest/assertables/macro.assert_fn_err.html) for functions that return `Result::Err`.
+
+Modules for readers:
+
+* [`assert_fs_read_to_string`](https://docs.rs/assertables/latest/assertables/macro.assert_fs_read_to_string.html) for file system path contents.
+
+* [`assert_io_read_to_string`](https://docs.rs/assertables/latest/assertables/macro.assert_io_read_to_string.html) for input/output reader streams.
+
+Modules for external calls:
+
+* [`assert_command`](https://docs.rs/assertables/latest/assertables/macro.assert_command.html) for commands and their stdout & stderr.
+
+* [`assert_program_args`](https://docs.rs/assertables/latest/assertables/macro.assert_program_args.html) for programs with arguments and their stdout & stderr.
+
 
 ### Benefits
 
@@ -93,17 +122,6 @@ your code.
 * Zero dependencies: the crate has no release dependencies, and just a short list of development dependencies.
 
 
-### Forms
-
-Assertables macros come in three forms:
-
-* Panic macro: `assert_*` is for typical test uses with `cargo test`.
-
-* Debug macro: `debug_assert_*` is for runtime diagnostic configuration.
-
-* Result macro:  `assert_*_as_result` is for runtime production configuration, such as for site reliability engineering, chaos engineering, validations, verifications, sanitizations, and more.
-
-
 ### Naming conventions
 
 Abbreviations:
@@ -120,8 +138,7 @@ Abbreviations:
 
 * `ge` ≈ greater than or equal.
 
-
-Shorthands:
+Types:
 
 * `path` ≈ implements `AsRef<Path>` such as `std::path::PathBuf`.
 
@@ -138,159 +155,53 @@ Shorthands:
   key counts.
 
 
-## Complete list of assert macros
-
-
-### assert_* for values
-
-Compare values:
-
-* `assert_eq!(a, b)` ≈ a = b
-
-* `assert_ne!(a, b)` ≈ a ≠ b
-
-* `assert_ge!(a, b)` ≈ a ≥ b
-
-* `assert_gt!(a, b)` ≈ a > b
-
-* `assert_le!(a, b)` ≈ a ≤ b
-
-* `assert_lt!(a, b)` ≈ a < b
-
-
-## For infix operators
-
-Compare values by using an infix value operator:
-
-* `assert_infix!(a == b)` ≈ a == b
-
-* `assert_infix!(a != b)` ≈ a ≠ b
-
-* `assert_infix!(a < b)` ≈ a < b
-
-* `assert_infix!(a <= b)` ≈ a ≤ b
-
-* `assert_infix!(a > b)` ≈ a > b
-
-* `assert_infix!(a >= b)` ≈ a ≥ b
-
-Relate values by using an infix logical operator:
-
-* `assert_infix!(a & b)` ≈ a ∧ b ≈ a AND b
-
-* `assert_infix!(a | b)` ≈ a ∨ b ≈ a OR b
-
-* `assert_infix!(a ^ b)` ≈ a ⊻ b ≈ a XOR b
-
-* `assert_infix!(a && b)` ≈ a …∧ b ≈ a lazy AND b
-
-* `assert_infix!(a || b)` ≈ a …∨ b ≈ a lazy OR b
-
-
-### For nearness
-
-Compare values by using nearness math conventions:
-
-* `assert_in_delta!(a, b, delta)` ≈ | a - b | ≤ delta
-
-* `assert_in_epsilon(a, b, epsilon)` ≈ | a - b | ≤ epsilon * min(a, b)
-
-
-### For strings
-
-These macros help with strings and also other structures that provide
-matchers such as `starts_with`, `ends_width`, `contains`, and `is_match`.
-Each macro also has a corresponding `not` version.
-
-* `assert_starts_with(a, b)` ≈ a.starts_with(b)
-
-* `assert_ends_with(a, b)` ≈ a.ends_with(b)
-
-* `assert_contains(container, containee)` ≈ container.contains(containee)
-
-* `assert_is_match(matcher, matchee)` ≈ matcher.is_match(matchee)
-
-
-### For much more
-
-There are many more macros that are conveniently grouped into modules.
-
-For enums:
-
-* [`assert_option`] for `Option` (`Some`, `None`)
-
-* [`assert_result`] for `Result` (`Ok`, `Err`)
-
-For collections, such as arrays, vectors, lists, maps:
-
-* [`assert_set`] for set collections
-
-* [`assert_bag`] for bag collections
-
-For functions:
-
-* [`assert_fn`] for functions in general.
-
-* [`assert_fn_ok`] for functions that return Result::Ok.
-
-* [`assert_fn_err`] for functions that return Result::Err.
-
-For readers:
-
-* [`assert_fs_read_to_string`] for file system path contents.
-
-* [`assert_io_read_to_string`] for input/output reader streams.
-
-For external calls:
+## Forms
 
-* [`assert_command`] for commands and their stdout & stderr.
 
-* [`assert_program_args`] for programs with args and their stdout & stderr.
+### Forms for panic! versus Err()
 
+All the assert macros have 3 forms that you can use depending on your goals.
 
-## Forms
+Panic form for typical tests:
 
+* [`assert_starts_with!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_starts_with.html)
 
-### Forms for panic! versus Err()
+Debug form for runtime:
 
-The assert macros have three forms that you can use depending on your goals:
+* [`debug_assert_starts_with!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.debug_assert_starts_with.html)
 
+Result form for runtime, validation, verification, sanitization, and more:
 
-```rust
-assert_gt!(a, b); // return () or panic!(…), for typical compile-time testing
+* [`assert_starts_with_as_result!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_starts_with_as_result.html); // return Result Ok(()) or Err(…), for any runtime
 
-debug_assert_gt!(a, b); // return () or panic!(…), for a non-optimized runtime
 
-assert_gt_as_result!(a, b); // return Result Ok(()) or Err(…), for any runtime
-```
+### Forms for messages
 
+All the assert macros have 2 forms that are for default messages versus custom messages.
 
-### Forms for messages
+Default message form:
 
-The assert macros have forms for default messages versus custom messages.
+* [`assert_starts_with!(a, b)`](https://docs.rs/assertables/latest/assertables/macro.assert_starts_with.html)
 
-```rust
-assert_gt!(1, 2); // panic!("assertion failed: assert_gt(1, 2)…")
+Custom message form:
 
-assert_gt!(1, 2, "message"); // panic!("message")
-```
+* [`assert_starts_with!(a, b, "Your custom message here")`](https://docs.rs/assertables/latest/assertables/macro.assert_starts_with.html)
 
 
 ### Forms for comparing an other versus an expression
 
-Some assert macros have forms for comparing an other versus an expression:
+Many of the assert macros have 2 forms that are for comparing an item to an other of the same type versus to an expression.
 
-```rust
-assert_io_read_to_string_eq!(reader1, reader2); // reader1.read_to_string() = reader2.read_to_string()
+Compare an item to an other i.e. of the same type:
+
+* [`assert_io_read_to_string_eq!(reader1, reader2)`](https://docs.rs/assertables/latest/assertables/macro.assert_io_read_to_string_eq.html)
 
-assert_io_read_to_string_eq_expr!(reader, expr); // reader1.read_to_string() = expr
-```
+Compare an item to an expression:
 
-
-## Change highlights
+* [`assert_io_read_to_string_eq_expr!(reader, expr)`](https://docs.rs/assertables/latest/assertables/macro.assert_io_read_to_string_eq_expr.html)
 
 
-### Version 8
+## Change highlights
 
 8.2:
 
@@ -310,17 +221,15 @@ assert_io_read_to_string_eq_expr!(reader, expr); // reader1.read_to_string() = e
 
 * Breaking change: rename `assert_read_to_string_*` macros to `assert_io_read_to_string_*`. If you use these macros, then please update your code to use the new naming convention.
 
-
-### Version 7
+7.x:
 
 * Add `assert_in_delta`, `assert_in_epsilon`.
 
 * Add `assert_fn_*` macros with multiple arities.
 
 * Add `cargo release` for optimized tagged releases.
 
-
-### Version 6
+6.x:
 
 * Add `assert_starts_with`, `assert_ends_with`, `assert_contains`, `assert_is_match`.
 
@@ -332,8 +241,8 @@ assert_io_read_to_string_eq_expr!(reader, expr); // reader1.read_to_string() = e
 ## Tracking
 
 * Package: assertables-rust-crate
-* Version: 8.2.0
+* Version: 8.2.1
 * Created: 2021-03-30T15:47:49Z
-* Updated: 2024-09-04T20:21:53Z
+* Updated: 2024-09-07T12:31:17Z
 * License: MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or contact us for more
 * Contact: Joel Parker Henderson ([email protected])

book.md

@@ -123,7 +123,7 @@ assertion failed: `assert_fn_ok_eq!(left_function, left_input, right_function, r
 ```
 
 
-Rust `assertables` provides these macros for functions that return a Result of Ok or Err:
+Rust `assertables` provides these macros for functions that return a Result of `Ok`, `Err`:
 
 * `assert_fn_ok_eq!`
 

doc/help.html

@@ -1 +1 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Documentation for Rustdoc"><title>Help</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="./static.files/${f}">`).join(""))</script><link rel="stylesheet" href="./static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="./static.files/rustdoc-dd39b87e5fcfba68.css"><meta name="rustdoc-vars" data-root-path="./" data-static-root-path="./static.files/" data-current-crate="lib" data-themes="" data-resource-suffix="" data-rustdoc-version="1.80.1 (3f5fd8dd4 2024-08-06)" data-channel="1.80.1" data-search-js="search-d52510db62a78183.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="./static.files/storage-118b08c4c78b968e.js"></script><script defer src="./static.files/main-20a3ad099b048cf2.js"></script><noscript><link rel="stylesheet" href="./static.files/noscript-df360f571f6edeae.css"></noscript><link rel="alternate icon" type="image/png" href="./static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="./static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod sys"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><h2><a href="./index.html">Rustdoc</a><span class="version">1.80.1</span></h2></div><div class="version">(3f5fd8dd4 2024-08-06)</div><h2 class="location">Help</h2><div class="sidebar-elems"></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Rustdoc help</h1><span class="out-of-band"><a id="back" href="javascript:void(0)" onclick="history.back();">Back</a></span></div><noscript><section><p>You need to enable JavaScript to use keyboard commands or search.</p><p>For more information, browse the <a href="https://doc.rust-lang.org/rustdoc/">rustdoc handbook</a>.</p></section></noscript></section></div></main></body></html>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Documentation for Rustdoc"><title>Help</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="./static.files/${f}">`).join(""))</script><link rel="stylesheet" href="./static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="./static.files/rustdoc-c5d6553a23f1e5a6.css"><meta name="rustdoc-vars" data-root-path="./" data-static-root-path="./static.files/" data-current-crate="lib" data-themes="" data-resource-suffix="" data-rustdoc-version="1.81.0 (eeb90cda1 2024-09-04)" data-channel="1.81.0" data-search-js="search-d234aafac6c221dd.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="./static.files/storage-118b08c4c78b968e.js"></script><script defer src="./static.files/main-d2fab2bf619172d3.js"></script><noscript><link rel="stylesheet" href="./static.files/noscript-df360f571f6edeae.css"></noscript><link rel="alternate icon" type="image/png" href="./static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="./static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod sys"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="./index.html"><img class="rust-logo" src="./static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><h2><a href="./index.html">Rustdoc</a><span class="version">1.81.0</span></h2></div><div class="version">(eeb90cda1 2024-09-04)</div><h2 class="location">Help</h2><div class="sidebar-elems"></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Rustdoc help</h1><span class="out-of-band"><a id="back" href="javascript:void(0)" onclick="history.back();">Back</a></span></div><noscript><section><p>You need to enable JavaScript to use keyboard commands or search.</p><p>For more information, browse the <a href="https://doc.rust-lang.org/rustdoc/">rustdoc handbook</a>.</p></section></noscript></section></div></main></body></html>