updated add-watch doc

1 files changed, 9 insertions, 7 deletions

diff --git a/src/clj/clojure/core.clj b/src/clj/clojure/core.clj
index a54e0f23..1b54f5e5 100644
--- a/src/clj/clojure/core.clj
+++ b/src/clj/clojure/core.clj
@@ -1217,15 +1217,17 @@
   Adds a watch function to an agent/atom/var/ref reference. The watch
   fn must be a fn of 4 args: a key, the reference, its old-state, its
   new-state. Whenever the reference's state might have been changed,
-  any registered watches will have their functions sent. The watch fn
-  will be caled synchronously, on the agent's thread if an agent,
+  any registered watches will have their functions called. The watch fn
+  will be called synchronously, on the agent's thread if an agent,
   before any pending sends if agent or ref. Note that an atom's or
   ref's state may have changed again prior to the fn call, so use
-  old-state rather than derefing the reference. Note also that watch fns
-  may be called from multiple threads simultaneously. Var watchers are
-  triggered only by root binding changes, not thread-local set!s"
-  [#^clojure.lang.IRef reference key fn]
-  (.addWatch reference key fn))
+  old/new-state rather than derefing the reference. Note also that watch
+  fns may be called from multiple threads simultaneously. Var watchers
+  are triggered only by root binding changes, not thread-local
+  set!s. Keys must be unique per reference, and can be used to remove
+  the watch with remove-watch, but are otherwise considered opaque by
+  the watch mechanism."
+  [#^clojure.lang.IRef reference key fn] (.addWatch reference key fn))
 
 (defn remove-watch
   "Experimental.