Documentation updates.

README.md

@@ -1,4 +1,4 @@
-## Sol 2.0
+## Sol 2.2
 
 [![Build Status](https://travis-ci.org/ThePhD/sol2.svg?branch=develop)](https://travis-ci.org/ThePhD/sol2)
 [![Documentation Status](https://readthedocs.org/projects/sol2/badge/?version=latest)](http://sol2.readthedocs.org/en/latest/?badge=latest)

docs/source/api/function.rst

@@ -33,6 +33,8 @@ The following C++ code will call this function from this file and retrieve the r
 
 The call ``woof(20)`` generates a :ref:`function_result<function-result>`, which is then implicitly converted to an ``double`` after being called. The intermediate temporary ``function_result`` is then destructed, popping the Lua function call results off the Lua stack. 
 
+.. _function-result-warning:
+
 .. warning::
 
 	Do NOT save the return type of a :ref:`function_result<function-result>` with ``auto``, as in ``auto numwoof = woof(20);``, and do NOT store it anywhere. Unlike its counterpart :ref:`protected_function_result<protected-function-result>`, ``function_result`` is NOT safe to store as it assumes that its return types are still at the top of the stack and when its destructor is called will pop the number of results the function was supposed to return off the top of the stack. If you mess with the Lua stack between saving ``function_result`` and it being destructed, you will be subject to an incredible number of surprising and hard-to-track bugs. Don't do it.
@@ -52,7 +54,7 @@ The call ``woof(20)`` generates a :ref:`function_result<function-result>`, which
 Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types<int, std::string>, ...)`` syntax. Function assumes there are no runtime errors, and thusly will call the ``atpanic`` function if an error does occur.
 
 
-safety
-------
+function call safety
+--------------------
 
-You can have functions here and on usertypes check to definitely make sure that the types passed to C++ functions are what they're supposed to be by adding a ``#define SOL_CHECK_ARGUMENTS`` before including Sol, or passing it on the command line. Otherwise, for speed reasons, these checks are only used where absolutely necessary (like discriminating between :doc:`overloads<overload>`)
+You can have functions here and on usertypes check to definitely make sure that the types passed to C++ functions are what they're supposed to be by adding a ``#define SOL_CHECK_ARGUMENTS`` before including Sol, or passing it on the command line. Otherwise, for speed reasons, these checks are only used where absolutely necessary (like discriminating between :doc:`overloads<overload>`). See :doc:`safety<../safety>` for more information.

docs/source/api/state.rst

@@ -54,7 +54,7 @@ This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens
 	void script(const std::string& code);
 	void script_file(const std::string& filename);
 
-These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. 
+These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run isolated: any scripts or code run will affect code in other states as well: code ran in this fashion is not isolated. 
 
 .. code-block:: cpp
 	:caption: function: global table / registry table

docs/source/api/table.rst

@@ -30,7 +30,13 @@ members
 	template<typename T, typename... Keys>
 	decltype(auto) traverse_get(Keys&&... keys) const;
 
-These functions retrieve items from the table. The first one (``get``) can pull out *multiple* values, 1 for each key value passed into the function. In the case of multiple return values, it is returned in a ``std::tuple<Args...>``. It is similar to doing ``return table["a"], table["b"], table["c"]``. Because it returns a ``std::tuple``, you can use ``std::tie`` on a multi-get to retrieve all of the necessary variables. The second one (``traverse_get``) pulls out a *single* value,	using each successive key provided to do another lookup into the last. It is similar to doing ``x = table["a"]["b"]["c"][...]``.
+	template<typename T, typename Key, typename D>
+	decltype(auto) get_or(Key&& key, D&& otherwise) const;
+
+
+These functions retrieve items from the table. The first one (``get``) can pull out *multiple* values, 1 for each key value passed into the function. In the case of multiple return values, it is returned in a ``std::tuple<Args...>``. It is similar to doing ``return table["a"], table["b"], table["c"]``. Because it returns a ``std::tuple``, you can use ``std::tie``/``std::make_tuple`` on a multi-get to retrieve all of the necessary variables. The second one (``traverse_get``) pulls out a *single* value,	using each successive key provided to do another lookup into the last. It is similar to doing ``x = table["a"]["b"]["c"][...]``.
+
+If the keys within nested queries try to traverse into a table that doesn't exist, the second lookup into the nil-returned variable and belong will cause a panic to be fired by the lua C API. If you need to check for keys, check with ``auto x = table.get<sol::optional<int>>( std::tie("a", "b", "c" ) );``, and then use the :doc:`optional<optional>` interface to check for errors. As a short-hand, easy method for returning a default if a value doesn't exist, you can use ``get_or`` instead.
 
 .. code-block:: cpp
 	:caption: function: set / traversing set
@@ -133,4 +139,14 @@ Creates a table, optionally with the specified values pre-set into the table. If
 
 Creates a table, optionally with the specified values pre-set into the table. It checks every 2nd argument (the keys) and generates hints for how many array or map-style entries will be placed into the table.
 
+.. code-block:: cpp
+	:caption: function: create a named table with compile-time defaults assumed
+	:name: table-create-named
+
+	template <typename Name, typename... Args>
+	table create_named(Name&& name, Args&&... args);
+	
+
+Creates a table, optionally with the specified values pre-set into the table, and sets it as the key ``name`` in the table.
+
 .. _input iterators: http://en.cppreference.com/w/cpp/concept/InputIterator

docs/source/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Sol 2.1
+Sol 2.2
 =======
 a fast, simple C++ and Lua Binding
 ----------------------------------

docs/source/safety.rst

@@ -7,4 +7,11 @@ Sol was designed to be correct and fast, and in the pursuit of both uses the reg
 	* ``sol::stack::get`` (used everywhere) defaults to using ``sol::stack::check_get`` and dereferencing the argument. It uses ``sol::type_panic`` as the handler if something goes wrong.
 	* ``sol::stack::call`` and its variants will, if no templated boolean is specified, check all of the arguments for a function call.
 
-Remember that if you want these features, you must explicitly turn them on. Additionally, you can have basic boolean checks when using the API by just converting to a :doc:`sol::optional\<T><api/optional>` when necessary. Tests are compiled with this on to ensure everythign is going as expected.
+Remember that if you want these features, you must explicitly turn them on. Additionally, you can have basic boolean checks when using the API by just converting to a :doc:`sol::optional\<T><api/optional>` when necessary. Tests are compiled with this on to ensure everythign is going as expected.
+
+
+Finally, some warnings that may help with errors when working with Sol:
+
+.. warning::
+
+	Do NOT save the return type of a :ref:`function_result<function-result>` with ``auto``, as in ``auto numwoof = woof(20);``, and do NOT store it anywhere. See :ref:`here<function-result-warning>`.

docs/source/tutorial/variables.rst

@@ -16,6 +16,7 @@ reading
 
 .. code-block:: cpp
 	:caption: main.cpp
+	:name: variables-main-cpp
 
 	int main () {
 
@@ -29,6 +30,7 @@ You can interact with the variables like this:
 
 .. code-block:: cpp
 	:caption: main.cpp extended
+	:name: extended-variables-main-cpp
 
 	#include <utility> // for std::pair