From a2c01ae9ee56af0097f5b36fba6e3e47e1190b80 Mon Sep 17 00:00:00 2001
From: Charles Kawczynski <kawczynski.charles@gmail.com>
Date: Fri, 12 Mar 2021 12:20:56 -0800
Subject: [PATCH] Add docs on performance

---
 docs/make.jl            |  9 ++++++
 docs/src/api.md         |  8 ++++++
 docs/src/index.md       |  9 ------
 docs/src/performance.md | 63 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 80 insertions(+), 9 deletions(-)
 create mode 100644 docs/src/api.md
 create mode 100644 docs/src/performance.md

diff --git a/docs/make.jl b/docs/make.jl
index 1257875..8a4a1ff 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,13 +1,22 @@
 using Documenter, DispatchedTuples
 
+format = Documenter.HTML(
+    prettyurls = !isempty(get(ENV, "CI", "")),
+    collapselevel = 1,
+)
+
 makedocs(
     sitename = "DispatchedTuples.jl",
     strict = true,
+    format = format,
     checkdocs = :exports,
     clean = true,
+    doctest = true,
     modules = [DispatchedTuples],
     pages = Any[
         "Home" => "index.md",
+        "Performance" => "performance.md",
+        "API" => "api.md",
     ],
 )
 
diff --git a/docs/src/api.md b/docs/src/api.md
new file mode 100644
index 0000000..28cf76b
--- /dev/null
+++ b/docs/src/api.md
@@ -0,0 +1,8 @@
+# API
+
+```@docs
+DispatchedTuples.AbstractDispatchedTuple
+DispatchedTuples.DispatchedTuple
+DispatchedTuples.DispatchedSet
+DispatchedTuples.dispatch
+```
diff --git a/docs/src/index.md b/docs/src/index.md
index 23e773a..a24112f 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -46,12 +46,3 @@ dispatch(dtup, Baz()) # returns ()
 ```
 
 For convenience, `DispatchedTuple` can alternatively take a `Tuple` of two-element `Tuple`s.
-
-## API
-
-```@docs
-DispatchedTuples.AbstractDispatchedTuple
-DispatchedTuples.DispatchedTuple
-DispatchedTuples.DispatchedSet
-DispatchedTuples.dispatch
-```
diff --git a/docs/src/performance.md b/docs/src/performance.md
new file mode 100644
index 0000000..ead707f
--- /dev/null
+++ b/docs/src/performance.md
@@ -0,0 +1,63 @@
+# Performance
+
+The performance of `DispatchedTuple`s should scale similar to the performance of ordinary tuples (good with small tuples, but expensive with larger ones).
+
+```@example perf
+using DispatchedTuples
+using InteractiveUtils
+
+struct Foo end;
+struct Bar end;
+struct Baz end;
+
+tup = (
+   Pair(Foo(), 1),
+   Pair(Bar(), 3),
+   Pair(Foo(), 2),
+)
+
+tupset = (
+   Pair(Foo(), 1),
+   Pair(Bar(), 3),
+   Pair(Baz(), 2),
+)
+dtup = DispatchedTuple(tup);
+dset = DispatchedSet(tupset);
+nothing
+```
+
+Using `dispatch` on a `DispatchedTuple` is equivalent to hard-coding the intended indexes ahead of time, which means that the LLVM code is concise:
+
+## DispatchedTuple
+
+```@example perf
+get_foo_magic(dtup) = (dtup.tup[1][2], dtup.tup[3][2])
+@code_typed get_foo_magic(dtup)
+```
+```@example perf
+@code_typed dispatch(dtup, Foo())
+```
+
+```@example perf
+@code_native get_foo_magic(dtup)
+```
+```@example perf
+@code_native dispatch(dtup, Foo())
+```
+
+## DispatchedSet
+
+```@example perf
+get_foo_magic(dset) = dset.tup[1][2]
+@code_typed get_foo_magic(dset)
+```
+```@example perf
+@code_typed dispatch(dset, Foo())
+```
+
+```@example perf
+@code_native get_foo_magic(dset)
+```
+```@example perf
+@code_native dispatch(dset, Foo())
+```