From 715d0474cf64fbc901b0cbab2f7baee36fa5c18b Mon Sep 17 00:00:00 2001
From: David Greenspan <dgreenspan@alum.mit.edu>
Date: Mon, 18 Aug 2014 17:27:02 -0700
Subject: [PATCH] Document UI.ReactiveVar

---
 docs/client/api.html | 43 +++++++++++++++++++++++++++++++++++++++++++
 docs/client/api.js   | 16 ++++++++++++++++
 docs/client/docs.js  |  1 +
 3 files changed, 60 insertions(+)

diff --git a/docs/client/api.html b/docs/client/api.html
index 987da3abf7..67e7757ac5 100644
--- a/docs/client/api.html
+++ b/docs/client/api.html
@@ -2576,6 +2576,49 @@ be able to construct your own custom Template objects.  For example, you can:
 
 {{> api_box ui_istemplate}}
 
+{{> api_box ui_reactivevar}}
+
+A ReactiveVar holds a single value that can be get and set, such that calling
+`set` will invalidate any Computations that called `get`, according to the
+usual contract for reactive data sources.
+
+A ReactiveVar is similar to a Session variable, with a few differences:
+
+* ReactiveVars don't have global names, like the "foo" in `Session.get("foo")`.
+  Instead, they may be created and used locally, for example attached to a
+  template instance, as in: `this.foo.get()`.
+
+* ReactiveVars are not automatically migrated across hot code pushes,
+  whereas Session state is.
+
+* ReactiveVars can hold any value, while Session variables are limitd to
+  JSON or EJSON.
+
+An important property of ReactiveVars &mdash; which is sometimes a
+reason for using one &mdash; is that setting the value to the same
+value as before has no effect; it does not trigger any invalidations.
+So if one autorun sets a ReactiveVar, and another autorun gets the
+ReactiveVar, a re-run of the first autorun won't necessarily trigger
+the second.  By default, only primitive values are compared this way,
+while calling `set` on an argument that is an *object* (not a
+primitive) always counts as a change.  You can configure this behavior
+using the `equalsFunc` argument.
+
+ReactiveVars have the following public methods:
+
+<dl class="objdesc">
+{{#dtdd name="get()" id="reactivevar_get"}}
+Returns the current value of the ReactiveVar, establishing a reactive
+dependency.
+{{/dtdd}}
+
+{{#dtdd name="set(newValue)" id="reactivevar_set"}}
+Sets the current value of the ReactiveVar, invalidating the Computations
+that called `get` if the new value is different from the old one.
+{{/dtdd}}
+</dl>
+
+
 {{#api_box eventmaps}}
 
 Several functions take event maps. An event map is an object where
diff --git a/docs/client/api.js b/docs/client/api.js
index ca75feaee3..b2d72a7612 100644
--- a/docs/client/api.js
+++ b/docs/client/api.js
@@ -2189,6 +2189,22 @@ Template.api.ui_istemplate = {
   ]
 };
 
+Template.api.ui_reactivevar = {
+  id: "ui_reactivevar",
+  name: "[new] UI.ReactiveVar(initialValue, [equalsFunc])",
+  locus: "Client",
+  descr: ["Constructor for a ReactiveVar, which represents a single reactive variable."],
+  args: [
+    {name: "initialValue",
+     type: "Any",
+     descr: "The initial value to set.  `equalsFunc` is ignored when setting the initial value."},
+    {name: "equalsFunc",
+     type: "Function",
+     descr: "Optional.  A function of two arguments, called on the old value and the new value whenever the ReactiveVar is set.  If it returns true, no set is performed.  If omitted, the default `equalsFunc` returns true if its arguments are `===` and are of type number, boolean, string, undefined, or null."
+    }
+  ]
+};
+
 Template.api.renderable_content = {
   id: "renderable_content",
   name: "Renderable content"
diff --git a/docs/client/docs.js b/docs/client/docs.js
index 07d57b379c..945ca9cf2e 100644
--- a/docs/client/docs.js
+++ b/docs/client/docs.js
@@ -282,6 +282,7 @@ var toc = [
       ],
       "UI.Template",
       "UI.isTemplate",
+      "UI.ReactiveVar",
       {type: "spacer"},
       {name: "Event maps", style: "noncode"},
       {name: "Renderable content", id: "renderable_content", style: "noncode"}