Documentation update about functions and new typedefs.

docs/source/api/function.rst

@@ -10,6 +10,7 @@ calling functions bound to Lua
 .. code-block:: cpp
 	
 	class function : public reference;
+	typedef function unsafe_function;
 
 Function is a correct-assuming version of :doc:`protected_function<protected_function>`, omitting the need for typechecks and error handling. It is the default function type of Sol. Grab a function directly off the stack using the constructor:
 

docs/source/api/protected_function.rst

@@ -6,8 +6,9 @@ Lua function calls that trap errors and provide error handling
 .. code-block:: cpp
 	
 	class protected_function : public reference;
+	typedef protected_function safe_function;
 
-Inspired by a request from `starwing<https://github.com/starwing>` in the old repository, this class provides the same interface as :doc:`function<function>` but with heavy protection and a potential error handler for any Lua errors and C++ exceptions. You can grab a function directly off the stack using the constructor, or pass to it 2 valid functions, which we'll demonstrate a little later.
+Inspired by a request from `starwing`_ in the :doc:`old sol repository<../origin>`, this class provides the same interface as :doc:`function<function>` but with heavy protection and a potential error handler for any Lua errors and C++ exceptions. You can grab a function directly off the stack using the constructor, or pass to it 2 valid functions, which we'll demonstrate a little later.
 
 When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :doc:`protected_function_result<proxy>` class that gets implicitly converted to the requested return type. For example:
 
@@ -185,3 +186,5 @@ The error-handler that is called should a runtime error that Lua can detect occu
 	``protected_function_result`` safely pops its values off the stack when its destructor is called, keeping track of the index and number of arguments that were supposed to be returned. If you remove items below it using ``lua_remove``, for example, it will not behave as expected. Please do not perform fundamentally stack-rearranging operations until the destructor is called (pushing/popping above it is just fine).
 
 To know more about how function arguments are handled, see :ref:`this note<function-argument-handling>`.
+
+.. _starwing: https://github.com/starwing

docs/source/errors.rst

@@ -23,6 +23,8 @@ It is preferred if you catch an error that you log what happened, terminate the
 
 Lua is a C API first and foremost: exceptions bubbling out of it is essentially last-ditch, terminal behavior that the VM does not expect. You can see an example of handling a panic on the exceptions page :ref:`here<typical-panic-function>`.
 
+Furthermore, it would be a great idea for you to use the safety features talked about :doc:`safety section<safety>`, especially for those related to functions.
+
 
 Destructors and Safety
 ----------------------

docs/source/safety.rst

@@ -3,6 +3,9 @@ safety
 
 Sol was designed to be correct and fast, and in the pursuit of both uses the regular ``lua_to{x}`` functions of Lua rather than the checking versions (``lua_check{X}``) functions. The API defaults to paranoidly-safe alternatives if you have a ``#define SOL_CHECK_ARGUMENTS`` before you include Sol, or if you pass the ``SOL_CHECK_ARGUMENTS`` define on the build command for your build system. By default, it is off and remains off unless you define this, even in debug mode. The same goes for ``#define SOL_SAFE_USERTYPE``.
 
+config
+------
+
 Note that you can obtain safety with regards to functions you bind by using the :doc:`protect<api/protect>` wrapper around function/variable bindings you set into Lua. Additionally, you can have basic boolean checks when using the API by just converting to a :doc:`sol::optional\<T><api/optional>` when necessary for getting things out of Lua and for function arguments.
 
 ``SOL_SAFE_USERTYPE`` triggers the following change:
@@ -17,6 +20,14 @@ Tests are compiled with this on to ensure everything is going as expected. Remem
 
 Finally, some warnings that may help with errors when working with Sol:
 
+
+functions
+---------
+
+The *vast majority* of all users are going to want to work with :doc:`sol::safe_function/sol::protected_function<api/protected_function>`. This version allows for error checking, prunes results, and responds to the defines listed above by throwing errors if you try to use the result of a function without checking. :doc:`sol::function/sol::unsafe_function<api/function>` is unsafe. It assumes that its contents run correctly and throw no errors, which can result in crashes that are hard to debug while offering a very tiny performance boost for not checking error codes or catching exceptions.
+
+If you find yourself crashing inside of ``sol::function``, try changing it to a ``sol::protected_function`` and seeing if the error codes and such help you find out what's going on. You can read more about the API on :doc:`the page itself<api/protected_function>`.
+
 .. 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>`.

single/sol/sol.hpp

@@ -20,8 +20,8 @@
 // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 // This file was generated with a script.
-// Generated 2017-02-15 10:41:27.152230 UTC
-// This header was generated with sol v2.15.7 (revision fe8b1c1)
+// Generated 2017-02-16 04:42:52.309916 UTC
+// This header was generated with sol v2.15.8 (revision 4aee6d3)
 // https://github.com/ThePhD/sol2
 
 #ifndef SOL_SINGLE_INCLUDE_HPP
@@ -3496,6 +3496,10 @@ namespace sol {
 	using protected_function = basic_protected_function<reference>;
 	using stack_function = basic_function<stack_reference>;
 	using stack_protected_function = basic_protected_function<stack_reference>;
+	using unsafe_function = basic_function<reference>;
+	using safe_function = basic_protected_function<reference>;
+	using stack_unsafe_function = basic_function<stack_reference>;
+	using stack_safe_function = basic_protected_function<stack_reference>;
 	template <typename base_t>
 	class basic_object;
 	template <typename base_t>

sol/types.hpp

@@ -514,6 +514,10 @@ namespace sol {
 	using protected_function = basic_protected_function<reference>;
 	using stack_function = basic_function<stack_reference>;
 	using stack_protected_function = basic_protected_function<stack_reference>;
+	using unsafe_function = basic_function<reference>;
+	using safe_function = basic_protected_function<reference>;
+	using stack_unsafe_function = basic_function<stack_reference>;
+	using stack_safe_function = basic_protected_function<stack_reference>;
 	template <typename base_t>
 	class basic_object;
 	template <typename base_t>