[ci skip] look at myyy docs, my docs are amaaazi-

Pfff no they're not. They're not amazing. They're crap.
Just. Like. Me.

docs/source/api/as_function.rst

@@ -24,6 +24,7 @@ This function serves the purpose of ensuring that a callable struct (like a lamb
 	lua.set( "not_func", callable() );
 	// Binds struct as function
 	lua.set( "func", sol::as_function( callable() ) );
-	// equivalent: lua.set_function( "func", sol::as_function( callable() ) );
+	// equivalent: lua.set_function( "func", callable() );
+	// equivalent: lua["func"] = callable();
 
 Note that if you actually want a userdata, but you want it to be callable, you simply need to create a :ref:`sol::table::new_usertype<new-usertype>` and then bind the ``"__call"`` metamethod (or just use ``sol::meta_function::call`` :ref:`enumeration<meta_function_enum>`).

docs/source/api/error.rst

@@ -10,6 +10,6 @@ the single error/exception type
 		error(const std::string& str): std::runtime_error("Lua: error: " + str) {}
 	};
 
-If an eror is thrown by Sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :ref:`sol::state<set-panic>`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are :doc:`nil<types>`.
+If an eror is thrown by Sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :ref:`sol::state<set-panic>`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are nil unless you specifically use it to pull errors out of things such as :doc:`sol::protected_function<protected_function>`.
 
 As it derives from ``std::runtime_error``, which derives from ``std::exception``, you can catch it with a ``catch (const std::exception& )`` clause in your try/catch blocks. You can retrieve a string error from Lua (Lua pushes all its errors as string returns) by using this type with any of the get or lookup functions in Sol.

docs/source/api/property.rst

@@ -43,8 +43,13 @@ These set of functions create a type which allows a setter and getter pair (or a
 	:caption: game.cpp
 	:linenos:
 
+	sol::state lua;
+	lua.open_libraries(sol::lib::base);
+
 	lua.set("theplayer", Player());
 
+	// Yes, you can register after you set a value and it will
+	// connect up the usertype automatically
 	lua.new_usertype<Player>( "Player",
 		"hp", sol::property(&Player::get_hp, &Player::set_hp),
 		"maxHp", sol::property(&Player::get_max_hp, &Player::set_max_hp)
@@ -54,5 +59,6 @@ These set of functions create a type which allows a setter and getter pair (or a
 .. code-block:: lua
 	:caption: game-snippet.lua
 
+	-- variable syntax, calls functions
 	theplayer.hp = 20
 	print(theplayer.hp)

docs/source/api/protect.rst

@@ -8,7 +8,7 @@ Routine to mark a function / variable as requiring safety
 	template <typename T>
 	auto protect( T&& value );
 
-``protect( my_func )`` allows you to protect a function call or member variable call when it is being set to Lua. It can be used with usertypes or when just setting a function into Sol. Below is an example that demonstrates that a call that would normally not error without :doc:`Safety features turn on<../safety>` that instead errors and makes the Lua safety-call wrapper ``pcall`` fail:
+``sol::protect( my_func )`` allows you to protect a function call or member variable call when it is being set to Lua. It can be used with usertypes or when just setting a function into Sol. Below is an example that demonstrates that a call that would normally not error without :doc:`Safety features turned on<../safety>` that instead errors and makes the Lua safety-call wrapper ``pcall`` fail:
 
 .. code-block:: cpp
 

docs/source/api/proxy.rst

@@ -18,24 +18,9 @@ proxy, (protected\_)function_result - proxy_base derivatives
 	struct protected_function_result: proxy_base<...>;
 
 
-These classes provide implicit ``operator=`` (``set``) and ``operator T`` (``get``) support for items retrieved from the underlying Lua implementation in Sol, specifically :doc:`sol::table<table>` and the results of function calls on :doc:`sol::function<function>` and :doc:`sol::protected_function<protected_function>`.
-
-
-.. _function-result:
-
-function_result
----------------
-
-``function_result`` is a temporary-only, intermediate-only implicit conversion worker for when :doc:`function<function>` is called. It is *NOT* meant to be stored or captured with ``auto``. It provides fast access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=``, as show below.
-
-
-.. _protected-function-result:
-
-protected_function_result
--------------------------
-
-``protected_function_result`` is a nicer version of ``function_result`` that can be used to detect errors. Its gives safe access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=``, as shown below.
+These classes provide implicit assignment operator ``operator=`` (for ``set``) and an implicit conversion operator ``operator T`` (for ``get``) to support items retrieved from the underlying Lua implementation, specifically :doc:`sol::table<table>` and the results of function calls on :doc:`sol::function<function>` and :doc:`sol::protected_function<protected_function>`.
 
+.. _proxy:
 
 proxy
 -----
@@ -174,6 +159,22 @@ stack_proxy
 
 ``sol::stack_proxy`` is what gets returned by :doc:`sol::variadic_args<variadic_args>` and other parts of the framework. It is similar to proxy, but is meant to alias a stack index and not a named function.
 
+.. _function-result:
+
+function_result
+---------------
+
+``function_result`` is a temporary-only, intermediate-only implicit conversion worker for when :doc:`function<function>` is called. It is *NOT* meant to be stored or captured with ``auto``. It provides fast access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=``, as shown below for :ref:`proxy<proxy>`.
+
+
+.. _protected-function-result:
+
+protected_function_result
+-------------------------
+
+``protected_function_result`` is a nicer version of ``function_result`` that can be used to detect errors. Its gives safe access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=``, as shown below for :ref:`proxy<proxy>`.
+
+
 .. _note 1:
 
 on function objects and proxies
@@ -197,4 +198,4 @@ Consider the following:
 	lua["object"] = doge{}; // bind constructed doge to "object"
 	// but it binds as a function
 
-When you use the ``lua["object"] = doge{};`` from above, keep in mind that Sol detects if this is a function *callable with any kind of arguments*. If ``doge`` has overriden ``return_type operator()( argument_types... )`` on itself, it may result in satisfying the ``requires`` constraint from above. This means that if you have a user-defined type you want to bind as a :doc:`userdata with usertype semantics<usertype>` with this syntax, it might get bound as a function and not as a user-defined type. use ``lua["object"].set(doge)`` directly to avoid this, or ``lua["object"].set_function(doge{})`` to perform this explicitly.
+When you use the ``lua["object"] = doge{};`` from above, keep in mind that Sol detects if this is a function *callable with any kind of arguments*. Since ``doge`` has overriden ``return_type operator()( argument_types... )`` on itself, it results in satisfying the ``requires`` constraint from above. This means that if you have a user-defined type you want to bind as a :doc:`userdata with usertype semantics<usertype>` with this syntax, it might get bound as a function and not as a user-defined type (d'oh!). use ``lua["object"].set(doge)`` directly to avoid this, or ``lua["object"].set_function(doge{})`` to perform this explicitly.

docs/source/api/readonly.rst

@@ -8,4 +8,4 @@ Routine to mark a member variable as read-only
 	template <typename T>
 	auto readonly( T&& value );
 
-The goal of read-only is to protect a variable set on a usertype or set as a function into Lua. Simply wrap it around a ``&my_class::my_member_variable`` in the appropriate place to use it.
+The goal of read-only is to protect a variable set on a usertype or a function. Simply wrap it around a member variable, e.g. ``sol::readonly( &my_class::my_member_variable )`` in the appropriate place to use it. If someone tries to set it, it will throw an error.

docs/source/api/state.rst

@@ -6,6 +6,7 @@ owning and non-owning state holders for registry and globals
 .. code-block:: cpp
 
 	class state_view;
+	
 	class state : state_view, std::unique_ptr<lua_State*, deleter>;
 
 The most important class here is ``state_view``. This structure takes a ``lua_State*`` that was already created and gives you simple, easy access to Lua's interfaces without taking ownership. ``state`` derives from ``state_view``, inheriting all of this functionality, but has the additional purpose of creating a fresh ``lua_State*`` and managing its lifetime for you in the default constructor.

docs/source/api/types.rst

@@ -63,7 +63,7 @@ This enumeration contains the status of a thread. The ``thread_status::dead`` st
 	    file    = LUA_ERRFILE,
 	};
 
-This enumeration contains the status of a load operation from :ref:`state::load(_file)<state-load-code>`. The ``thread_status::dead`` state is generated when the thread has nothing on its stack and it is not running anything.
+This enumeration contains the status of a load operation from :ref:`state::load(_file)<state-load-code>`.
 
 .. code-block:: cpp
 	:caption: type enumeration
@@ -94,7 +94,7 @@ type traits
 	:caption: lua_type_of trait
 	:name: lua-type-of
 
-	template <typename T, typename = void>
+	template <typename T>
 	struct lua_type_of;
 
 This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. The default value is ``type::userdata``.
@@ -110,12 +110,11 @@ This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. T
 	struct is_proxy_primitive;
 
 
-This trait is used by :doc:`proxy<proxy>` to know which types should be returned as references to internal Lua memory (e.g., ``userdata`` types) and which ones to return as values (strings, numbers, :doc:`references<reference>`). ``std::reference_wrapper``, ``std::tuple<...>`` are returned as values, but their contents are/can be references. The default value is false.
-
-.. nil:
+This trait is used by :doc:`proxy<proxy>` to know which types should be returned as references to internal Lua memory (e.g., ``userdata`` types) and which ones to return as values (strings, numbers, :doc:`references<reference>`). ``std::reference_wrapper``, ``std::tuple<...>`` are returned as values, but their contents can be references. The default value is false.
 
 special types
 -------------
+
 .. code-block:: cpp
 	:caption: nil
 	:name: nil
@@ -159,7 +158,7 @@ functions
 	type type_of(lua_State* L, int index);
 
 
-These functions get the type of a C++ type ``T`` or the type at the specified index on the Lua stack.
+These functions get the type of a C++ type ``T``; or the type at the specified index on the Lua stack.
 
 .. code-block:: cpp
 	:caption: type checking convenience functions
@@ -176,6 +175,8 @@ These functions get the type of a C++ type ``T`` or the type at the specified in
 
 	void type_assert(lua_State* L, int index, type expected);
 
+The purpose of these functions is to assert / throw / crash / error (or do nothing, as is the case with ``no_panic``). They're mostly used internally in the framework, but they're provided here if you should need them.
+
 .. code-block:: cpp
 	:caption: type name retrieval
 
@@ -197,7 +198,7 @@ structs
 	};
 
 	struct up_value_index {
-    	int index;
+    		int index;
 	};
 
 

docs/source/api/usertype.rst

@@ -256,21 +256,16 @@ For the rest of us safe individuals out there: You must specify the ``sol::base_
 		virtual int call() override { return 20; } 
 	};
 
-.. warning::
-
-	Sol currently attempts to link base class methods and variables with their derived classes with an undocumented, unsupported feature, provided you specify ``sol::base_classes<...>``. Unfortunately, this can come at the cost of prformance, depending on how "far" the base is from the derived class in the bases lookup list. If you do not want to suffer the performance degradation while we iron out the kinks in the implementation (and want it to stay performant forever), please specify all the base methods on the derived class in the method listing you write. In the future, we hope that with reflection we will not have to worry about this.
-
 Then, to register the base classes explicitly:
 
 .. code-block:: cpp
 	:linenos:
-	:emphasize-lines: 5,6
+	:emphasize-lines: 5
 
 	sol::state lua;
 
 	lua.new_usertype<B>( "B",
 		"call", &B::call,
-		// List bases explicitly if you disable exceptions
 		sol::base_classes, sol::bases<A>()
 	);
 
@@ -282,6 +277,11 @@ Then, to register the base classes explicitly:
 	
 	Sol does not support down-casting from a base class to a derived class at runtime.
 
+.. warning::
+
+	Sol currently attempts to link base class methods and variables with their derived classes with an undocumented, unsupported feature, provided you specify ``sol::base_classes<...>``. Unfortunately, this can come at the cost of prformance, depending on how "far" the base is from the derived class in the bases lookup list. If you do not want to suffer the performance degradation while we iron out the kinks in the implementation (and want it to stay performant forever), please specify all the base methods on the derived class in the method listing you write. In the future, we hope that with reflection we will not have to worry about this.
+
+
 inheritance + overloading
 -------------------------
 
@@ -303,7 +303,7 @@ traits
 	};
 
 
-This trait is used to provide names for the various metatables and global tables used to perform cleanup and lookup. They are automatically generated at runtime. In the case of RTTI being present, Sol will attempt to demangle the name from ``std::type_info`` to produce a valid name. If RTTI is disabled, Sol attempts to parse the output of ``__PRETTY_FUCNTION__`` (``g++``/``clang++``) or ``_FUNCDSIG`` (``vc++``) to get the proper type name. If you have a special need you can override the names for your specific type.
+This trait is used to provide names for the various metatables and global tables used to perform cleanup and lookup. They are automagically generated at runtime. Sol attempts to parse the output of ``__PRETTY_FUCNTION__`` (``g++``/``clang++``) or ``_FUNCDSIG`` (``vc++``) to get the proper type name. If you have a special need you can override the names for your specific type. If you notice a bug in a class name when you don't manually specify it during setting a usertype, feel free to open an issue request or send an e-mail!
 
 
 compilation speed