From 22f03863f2b790b1750af49aef64a42dac71a534 Mon Sep 17 00:00:00 2001
From: ThePhD <phdofthehouse@gmail.com>
Date: Sun, 7 Aug 2016 14:21:59 -0400
Subject: [PATCH] [ci-skip] docs update

---
 docs/source/api/api-top.rst |  1 +
 docs/source/api/var.rst     | 47 +++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 docs/source/api/var.rst

diff --git a/docs/source/api/api-top.rst b/docs/source/api/api-top.rst
index 82ea1a3d..c9133f9b 100644
--- a/docs/source/api/api-top.rst
+++ b/docs/source/api/api-top.rst
@@ -23,6 +23,7 @@ Browse the various function and classes :doc:`Sol<../index>` utilizes to make yo
    overload
    protect
    readonly
+   var
    resolve
    as_function
    property
diff --git a/docs/source/api/var.rst b/docs/source/api/var.rst
new file mode 100644
index 00000000..10956522
--- /dev/null
+++ b/docs/source/api/var.rst
@@ -0,0 +1,47 @@
+var
+===
+For hooking up static / global variables to Lua usertypes
+---------------------------------------------------------
+
+The sole purpose of this tagging type is to work with :doc:`usertypes<usertype>` to provide ``my_class.my_static_var`` access, and to also provide reference-based access as well.
+
+.. code-block:: cpp
+
+	struct test {
+		static int muh_variable;
+	};
+	int test::muh_variable = 25;
+	
+
+	int main () {
+		sol::state lua;
+		lua.open_libraries();
+		lua.new_usertype<test>("test",
+			"direct", sol::var(2),
+			"global", sol::var(test::muh_variable),
+			"ref_global", sol::var(std::ref(test::muh_variable)),
+		);
+
+		int direct_value = lua["test"]["straight"];
+		// direct_value == 2
+		
+		int global = lua["test"]["global"];
+		// global == 25
+		int global2 = lua["test"]["ref_global"];
+		// global2 == 25
+
+		test::muh_variable = 542;
+		
+		global = lua["test"]["global"];
+		// global == 25
+		// global is its own memory: was passed by value
+		
+		global2 = lua["test"]["ref_global"];
+		// global2 == 542
+		// global2 was passed through std::ref
+		// global2 holds a reference to muh_variable
+		// if muh_variable goes out of scope or is deleted
+		// problems could arise, so be careful!
+
+		return 0;
+	}