From 3b3a07bcb52cee3c360794f14b32217d346034f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kat=20March=C3=A1n?= <kzm@zkat.tech>
Date: Tue, 3 Aug 2021 12:57:20 -0700
Subject: [PATCH] docs: add thisdiagnostic example

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/README.md b/README.md
index c6fcf79..9941fa4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,70 @@
 you FAIL miette? you fail her compiler like the unsafe C program? oh! oh! jail for mother! jail for mother for One Thousand Years!!!!
 
 (I'm sorry, I'll come up with a better pun later.)
+
+## Examples
+
+Here's an example of using something like `thisdiagnostic` to define Diagnostics declaratively.
+
+```rust
+use thiserror::Error;
+use thisdiagnostic::Diagnostic;
+
+#[derive(Error, Diagnostic)]
+pub enum MyDiagnostic {
+    /// Generally happens because you did some specific thing wrong. The
+    /// reason is actually something like <...>
+    #[diagnostic(
+        code = fatal::error, // Translates to `mycrate::fatal::error` and creates
+                             // a crate-wide alias so you can just search for that
+                             // exact full string in rustdoc.
+        help = "Please consider doing things differently next time.",
+        backtrace = true, // Enable showing a backtrace when this is printed.
+    )]
+    #[error("Oopsie poopsie it all exploded.")]
+    FatalError,
+
+    /// This one usually resolves on its own, don't worry about it.
+    #[diagnostic(
+        code = nice::warning,
+        help = "This is mostly to help you!",
+        severity = warning
+    )]
+    #[error("This might break in the future.")]
+    NiceWarning,
+
+    /// This diagnostic includes code spans!
+    #[diagnostic(
+        code = math::bad_arithmetic,
+        help = "Convert {bad_var} into a {good_type} and try again."
+    )]
+    #[error("Tried to add a {bad_type} to a {good_type}")]
+    BadArithmetic {
+        src: PathBuf,
+        other_src: PathBuf,
+
+        good_type: Type,
+        bad_type: Type,
+        bad_var: Var,
+
+        #[span_source(src)]
+        #[label("This is a {bad_type}")]
+        bad_var_span: SourceSpan,
+
+        #[span_source(src)]
+        #[label("This is a {good_type}")]
+        good_var_span: Option<SourceSpan>,
+
+        #[span(other_src)]
+        #[label("{bad_var} is defined here")]
+        bad_var_definition_span: SourceSpan, // multiline span
+    },
+
+    #[error(transparent)]
+    #[diagnostic(transparent)]
+    // renders as "some_library::<code_subpath>". No docs needed.
+    // You must re-export `SomeLibraryError` from your crate if you want
+    // users to be able to find its error codes on your own rustdoc search box.
+    SomeLibraryError(#[from] some_library::SomeLibraryError)
+}
+```