From 3cf59fb451f6a938eb49d8fba50db4a73b7773ce Mon Sep 17 00:00:00 2001
From: Kevin Downey <hiredman@thelastcitadel.com>
Date: Fri, 3 Nov 2023 16:56:22 +0000
Subject: [PATCH] readme, docs, etc

---
 README.md                            | 20 ++++++++++++++++++++
 src/com/manigfeald/tagbody.clj       |  2 ++
 test/com/manigfeald/tagbody_test.clj | 20 --------------------
 3 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 5082100..b922a5b 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,9 @@ http://www.lispworks.com/documentation/HyperSpec/Body/s_tagbod.htm
 ## Usage
 
 ```clojure
+
+(require '[com.manigfeald.tagbody :refer [tagbody go]])
+
 (with-local-vars
   [v nil]
   (tagbody
@@ -30,6 +33,23 @@ http://www.lispworks.com/documentation/HyperSpec/Body/s_tagbod.htm
   (var-get v))
 ```
 
+## Limitations
+
+tagbody uses java.lang.Throwables to jump around. This can be
+problematic if you catch Throwables. Exception handles are also single
+threaded, so you cannot go across threads.
+
+The way tagbody currently runs it is limitted to 254 or so expressions
+in a tagbody.
+
+Expressions are converted to closures (fns) in a way that no doubt
+interfers with locals clearing.
+
+## Why?
+
+Maybe I can close the tagbody tab in my browser and stop thinking
+about it now.
+
 ## Me
 - @hiredman@downey.family
 - hiredman on clojurians.slack.com
diff --git a/src/com/manigfeald/tagbody.clj b/src/com/manigfeald/tagbody.clj
index c09d12c..5a7027d 100644
--- a/src/com/manigfeald/tagbody.clj
+++ b/src/com/manigfeald/tagbody.clj
@@ -14,6 +14,8 @@
 that can be jumped to via go in expressions in the dynamic extent of
   the tagbody.
 
+  Executes each expression in sequence. Returns nil.
+
   Limitted to 254 or so expressions. Uses throwables to jump, so if
   you are like me and catch Throwable everywhere, ¯\\_(ツ)_/¯
   
diff --git a/test/com/manigfeald/tagbody_test.clj b/test/com/manigfeald/tagbody_test.clj
index 4a7c7d1..aacbbf7 100644
--- a/test/com/manigfeald/tagbody_test.clj
+++ b/test/com/manigfeald/tagbody_test.clj
@@ -60,23 +60,3 @@
 (deftest common-lisp-hyperspec-example-2
   (is (= 2 (f1 nil)))
   (is (= 1 (f1 true))))
-
-
-
-(with-local-vars
-  [v nil]
-  (tagbody
-   (var-set v 1)
-   (go point-a)
-   (incf v 16)
-   point-c
-   (incf v 4)
-   (go point-b)
-   (incf v 32)
-   point-a
-   (incf v 2)
-   (go point-c)
-   (incf v 64)
-   point-b
-   (incf v 8))
-  (var-get v))
-- 
2.45.2