From 8f3ff38c41583a82108c0fb04f59877f2f24ef22 Mon Sep 17 00:00:00 2001
From: Nathan Daly <NHDaly@gmail.com>
Date: Wed, 1 Apr 2020 14:36:09 -0400
Subject: [PATCH] Add `Usage` section to the README

Explains how to use this package in three scenarios:
1. as a library author of a wrapped exception type
2. In client code, as a user of a potentially wrapped exception (e.g. any concurrent code)
3. In tests of potentially wrapped exceptions
---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index 9bac532..9c64d39 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,34 @@ that caused that Task to fail. Another example is the exception types in
 
 - `unwrap_exception_to_root(normal_exception) -> normal_exception`
 
+## Usage
+
+If your library provides a wrapped exception type, you should register it
+with this package by simply adding a method to `unwrap_exception`:
+```julia
+ExceptionUnwrapping.unwrap_exception(e::MyWrappedException) = e.exception
+```
+
+In client code, you should use `has_wrapped_exception` and `unwrap_exception_until`
+in catch blocks:
+```julia
+try
+    ...
+catch e
+    if has_wrapped_exception(e, BoundsError)
+        be = unwrap_exception_until(e, BoundsError)
+        # ...Use BoundsError...
+    else
+        rethrow()
+    end
+end
+```
+
+Finally, you can improve robustness in client tests via `@test_throws_wrapped`:
+```julia
+@test_throws_wrapped AssertionError my_possibly_multithreaded_function()
+```
+
 ## Motivating Example: Stable Exception Handling
 ### A Problem: Adding Concurrency to a Library Can Break Users' Exception Handling
 As we all start using concurrency more, exception handling can get a bit weird. Julia's