From 1c5a1bdb69936d07058a0053aacd798f3cc2676d Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Sun, 29 Dec 2024 18:39:39 +0000
Subject: [PATCH] docs(print): add details to readme and an example

---
 README.md           | 30 ++++++++++++++++++++++++++----
 src/print/macros.rs |  2 ++
 src/print/mod.rs    |  3 +++
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 461695e..a47b132 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,15 @@
 # kxio
 
-`kxio` is a Rust library that provides injectable `FileSystem` and `Network`
-resources to enhance the testability of your code. By abstracting system-level
-interactions, `kxio` enables easier mocking and testing of code that relies on
-file system and network operations.
+`kxio` is a Rust library that provides injectable `FileSystem`, `Network` and
+`Print` resources to enhance the testability of your code. By abstracting
+system-level interactions, `kxio` enables easier mocking and testing of code
+that relies on file system and network operations.
 
 ## Features
 
 - **Filesystem Abstraction**
 - **Network Abstraction**
+- **Print Abstraction**
 - **Enhanced Testability**
 
 ## Filesystem
@@ -30,6 +31,27 @@ The Network module offers a testable interface over the `reqwest` crate. For
 comprehensive documentation and usage examples, please refer to
 <https://docs.rs/kxio/latest/kxio/net/>
 
+## Print
+
+The Print module provides three implementations of the `Printer` trait:
+
+- `StandardPrint` - behaves as normal, printing to `STDOUT` and `STDERR`
+- `NullPrint` - swallows all prints, outputting nothing
+- `TestPrint` - captures all print output and makes it available for assertions in tests
+
+It also provides macros to use with each:
+
+- `kxprintln`
+- `kxprint`
+- `kxeprintln`
+- `kxeprint`
+
+They are analogous to the `std` macros: `println`, `print`, `eprintln` and `eprint` respectively.
+
+Each of the `kx{e}print{ln}` macros takes a reference to an instance of the `Printer` trait as the first parameter.
+
+For comprehensive documentation and usage examples, please refer to <https://docs.rs/kxio/latest/kxio/print/>
+
 ## Getting Started
 
 Add `kxio` to your `Cargo.toml`:
diff --git a/src/print/macros.rs b/src/print/macros.rs
index ea68cdd..c2198b8 100644
--- a/src/print/macros.rs
+++ b/src/print/macros.rs
@@ -1,3 +1,5 @@
+/// Macro to print the expression to the `Printer` with a trailing newline.
+/// 
 #[macro_export]
 macro_rules! kxprintln {
     ($printer:expr, $($arg:tt)*) => {{
diff --git a/src/print/mod.rs b/src/print/mod.rs
index 3b68591..a7215ad 100644
--- a/src/print/mod.rs
+++ b/src/print/mod.rs
@@ -11,6 +11,7 @@
 //!
 //! ```
 //! use kxio::print::{Print, StandardPrint};
+//! use kxio::{kxeprintln, kxprintln};
 //!
 //! fn print_hello(printer: &impl Print) {
 //!     printer.println("Hello, World!");
@@ -18,6 +19,8 @@
 //!
 //! let printer = StandardPrint;
 //! print_hello(&printer);
+//! kxprintln!(&printer, "Hello, world!");
+//! kxeprintln!(&printer, "Terminating!");
 //! ```
 
 mod macros;