[ci skip] update documentation

docs/source/api/c_call.rst

@@ -11,7 +11,9 @@ Templated type to transport functions through templates
 	template <typename... Functions>
 	int c_call (lua_State* L);
 
-The goal of ``sol::c_call<...>`` is to provide a way to wrap a function and transport it through a compile-time context. This enables faster speed at the cost of a much harder to read / poorer interface. ``sol::c_call`` expects a type for its first template argument, and a value of the previously provided type for the second template argument. To make a compile-time transported overloaded function, specify multiple functions in the same ``type, value`` pairing, but put it inside of a ``sol::wrap``. Note that is can also be placed into the argument list for a :doc:`usertype<usertype>` as well. 
+The goal of ``sol::c_call<...>`` is to provide a way to wrap a function and transport it through a compile-time context. This enables faster speed at the cost of a much harder to read / poorer interface, and can alleviate some template compilation speed issues. ``sol::c_call`` expects a type for its first template argument, and a value of the previously provided type for the second template argument. To make a compile-time transported overloaded function, specify multiple functions in the same ``type, value`` pairing, but put it inside of a ``sol::wrap``. Note that is can also be placed into the argument list for a :doc:`usertype<usertype>` as well. 
+
+This pushes a raw ``lua_CFunction`` into whatever you pass the resulting ``c_call`` function pointer into, whether it be a table or a userdata or whatever else using sol2's API. The resulting ``lua_CFunction`` can also be used directly with the lua API, just like many of sol2's types can be intermingled with Lua's API if you know what you're doing.
 
 It is advisable for the user to consider making a macro to do the necessary ``decltype( &function_name, ), function_name``. Sol does not provide one because many codebases already have `one similar to this`_.
 
@@ -24,7 +26,9 @@ Here's an example below of various ways to use ``sol::c_call``:
 	#include "sol.hpp"
 
 	int f1(int) { return 32; }
+
 	int f2(int, int) { return 1; }
+
 	struct fer {
 		double f3(int, int) {
 			return 2.5;

docs/source/api/stack.rst

@@ -45,8 +45,6 @@ members
 
 Retrieves the value of the object at ``index`` in the stack. The return type varies based on ``T``: with primitive types, it is usually ``T``: for all unrecognized ``T``, it is generally a ``T&`` or whatever the extension point :ref:`stack::getter\<T><getter>` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\<T><getter>` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get<stack-check-get>` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :doc:`safety<../safety>`.
 
-`record`
-
 You may also retrieve an :doc:`sol::optional\<T><optional>` from this as well, to have it attempt to not throw errors when performing the get and the type is not correct.
 
 .. code-block:: cpp
@@ -90,6 +88,35 @@ Retrieves the value of the object at ``index`` in the stack, but does so safely.
 
 Based on how it is called, pushes a variable amount of objects onto the stack. in 99% of cases, returns for 1 object pushed onto the stack. For the case of a ``std::tuple<...>``, it recursively pushes each object contained inside the tuple, from left to right, resulting in a variable number of things pushed onto the stack (this enables multi-valued returns when binding a C++ function to a Lua). Can be called with ``sol::stack::push<T>( L, args... )`` to have arguments different from the type that wants to be pushed, or ``sol::stack::push( L, arg, args... )`` where ``T`` will be inferred from ``arg``. The final form of this function is ``sol::stack::multi_push``, which will call one ``sol::stack::push`` for each argument. The ``T`` that describes what to push is first sanitized by removing top-level ``const`` qualifiers and reference qualifiers before being forwarded to the extension point :ref:`stack::pusher\<T><pusher>` struct.
 
+.. code-block:: cpp
+	:caption: function: push_reference
+	:name: stack-push-reference
+
+	// push T inferred from call site, pass args... through to extension point
+	template <typename T, typename... Args>
+	int push_reference( lua_State* L, T&& item, Args&&... args )
+
+	// push T that is explicitly specified, pass args... through to extension point
+	template <typename T, typename Arg, typename... Args>
+	int push_reference( lua_State* L, Arg&& arg, Args&&... args )
+
+	// recursively call the the above "push" with T inferred, one for each argument
+	template <typename... Args>
+	int multi_push_reference( lua_State* L, Args&&... args )
+
+
+These functinos behave similarly to the ones above, but they check for specific criteria and instead attempt to push a reference rather than forcing a copy if appropriate. Use cautiously as sol2 uses this mainly as a return from usertype functions and variables to preserve chaining/variable semantics from that a class object. Its internals are updated to fit the needs of sol2 and while it generally does the "right thing" and has not needed to be changed for a while, sol2 reserves the right to change its internal detection mechanisms to suit its users needs at any time, generally without breaking backwards compatibility and expectations but not exactly guaranteed.
+
+.. code-block:: cpp
+	:caption: function: pop
+	:name: stack-pop
+
+	// push T inferred from call site, pass args... through to extension point
+	template <typename... Args>
+	auto pop( lua_State* L, int index, ... )
+
+
+
 .. code-block:: cpp
 	:caption: function: set_field
 

docs/source/api/types.rst

@@ -197,11 +197,30 @@ structs
 		void* value;
 	};
 
-	struct up_value_index {
+	struct upvalue_index {
+    		int index;
+	};
+
+	struct raw_index {
+    		int index;
+	};
+
+	struct absolute_index {
+    		int index;
+	};
+
+	struct ref_index {
     		int index;
 	};
 
 
 Types that differentiate between the two kinds of ``void*`` Lua hands back from its API: full userdata and light userdata, as well as a type that modifies the index passed to ``get`` to refer to `up values`_ These types can be used to trigger different underlying API calls to Lua when working with :doc:`stack<stack>` namespace and the ``push``/``get``/``pop``/``check`` functions.
 
-.. _up values: http://www.Lua.org/manual/5.3/manual.html#4.4
+The ``raw_index`` type is used to tell a :doc:`sol::reference<api/reference>` type or similar that the desired index -- negative or not -- should be passed through directly to the API.
+
+The ``absolute_index`` type is used to tell a :doc:`sol::reference<api/reference>` type or similar that the desired index -- negative or not -- should be passed through Lua's `lua_absindex`_ function first to adjust where it is, and then given to the underlying API.
+
+The ``ref_index`` type is used to tell a :doc:`sol::reference<api/reference>` type or similar that it should look into the Lua C Registry for its type.
+
+.. _up values: http://www.Lua.org/manual/5.3/manual.html#4.4
+.. _lua_absindex: https://www.lua.org/manual/5.3/manual.html#lua_absindex