[ci skip] update docs

docs/source/api/unique_usertype_traits.rst

@@ -18,7 +18,7 @@ unique_usertype_traits<T>
 		static type* get (const actual_type&) {...}
 	};
 
-This is a customization point for users who need to *work with special kinds of pointers/handles*. For generic customization, please review the :doc:`customization tutorial<../tutorial/customization>` A traits type for alerting the library that a certain type is to be pushed as a special userdata with special deletion / destruction semantics. It is already defined for ``std::unique_ptr<T, D>`` and ``std::shared_ptr<T>``. You can specialize this to get ``unique_usertype_traits`` semantics with your code, for example with ``boost::shared_ptr<T>`` like so:
+This is a customization point for users who need to *work with special kinds of pointers/handles*. The traits type alerts the library that a certain type is to be pushed as a special userdata with special deletion / destruction semantics, like many smart pointers / custom smart pointers / handles It is already defined for ``std::unique_ptr<T, D>`` and ``std::shared_ptr<T>``. You can specialize this to get ``unique_usertype_traits`` semantics with your code. For example, here is how ``boost::shared_ptr<T>`` would look:
 
 .. code-block:: cpp
 	
@@ -39,6 +39,8 @@ This is a customization point for users who need to *work with special kinds of
 		}
 	}
 
-This will allow the framework to properly handle ``boost::shared_ptr<T>``, with ref-counting and all. The `type` is the  type that lua and sol will interact with, and will allow you to pull out a non-owning reference / pointer to the data when you just ask for a plain `T*` or `T&` or `T` using the getter functions and properties of Sol.
+This will allow the library to properly handle ``boost::shared_ptr<T>``, with ref-counting and all. The ``type`` is the type that lua and sol will interact with, and will allow you to pull out a non-owning reference / pointer to the data when you just ask for a plain ``T*`` or ``T&`` or ``T`` using the getter functions and properties of Sol. The ``actual_type`` is just the "real type" that controls the semantics (shared, unique, ``CComPtr``, ``ComPtr``, OpenGL handles, DirectX objects, the list goes on).
 
-Note that if ``is_null`` triggers, a ``nil`` value will be pushed into Sol.
+.. note::
+	
+	If ``is_null`` triggers (returns ``true``), a ``nil`` value will be pushed into Lua rather than an empty structure.

docs/source/tutorial/all-the-things.rst

@@ -5,6 +5,11 @@ These are all the things. Use your browser's search to find things you want.
 
 You'll need to ``#include <sol.hpp>``/``#include "sol.hpp"`` somewhere in your code. Sol is header-only, so you don't need to compile anything.
 
+.. note::
+
+	After you learn the basics of sol, it is usually advised that if you think something can work, you should TRY IT. It will probably work!
+	
+
 opening a state
 ---------------
 
@@ -633,18 +638,22 @@ You can emulate namespacing by having a table and giving it the namespace names
 
 This technique can be used to register namespace-like functions and classes. It can be as deep as you want. Just make a table and name it appropriately, in either Lua script or using the equivalent Sol code. As long as the table FIRST exists (e.g., make it using a script or with one of Sol's methods or whatever you like), you can put anything you want specifically into that table using :doc:`sol::table's<../api/table>` abstractions.
 
-advanced
---------
+there is a LOT more
+-------------------
 
-Some more advanced things you can do/read about:
+Some more things you can do/read about:
+	* :doc:`the usertypes page<../usertypes>` lists the huge amount of features for functions
+		- :doc:`unique usertype traits<../api/unique_usertype_traits>` allows you to specialize handle/RAII types from other libraries frameworks, like boost and Unreal, to work with Sol. Allows custom smart pointers, custom handles and others
+	* :doc:`the containers page<../containers>` gives full information about handling everything about container-like usertypes
+	* :doc:`the functions page<../functions.rst>` lists a myriad of features for functions
+		- :doc:`variadic arguments<../api/variadic_args>` in functions with ``sol::variadic_args``.
+		- also comes with :doc:`variadic_results<../api/variadic_results>` for returning multiple differently-typed arguments
+		- :doc:`this_state<../api/this_state>` to get the current ``lua_State*``, alongside other transparent argument types
 	* :doc:`metatable manipulations<../api/metatable_key>` allow a user to change how indexing, function calls, and other things work on a single type.
 	* :doc:`ownership semantics<ownership>` are described for how Lua deals with its own internal references and (raw) pointers.
 	* :doc:`stack manipulation<../api/stack>` to safely play with the stack. You can also define customization points for ``stack::get``/``stack::check``/``stack::push`` for your type.
 	* :doc:`make_reference/make_object convenience function<../api/make_reference>` to get the same benefits and conveniences as the low-level stack API but put into objects you can specify.
 	* :doc:`stack references<../api/stack_reference>` to have zero-overhead Sol abstractions while not copying to the Lua registry.
-	* :doc:`unique usertype traits<../api/unique_usertype_traits>` allows you to specialize handle/RAII types from other frameworks, like boost and Unreal, to work with Sol.
-	* :doc:`variadic arguments<../api/variadic_args>` in functions with ``sol::variadic_args``.
-	* :doc:`this_state<../api/this_state>` to get the current ``lua_State*``.
 	* :doc:`resolve<../api/resolve>` overloads in case you have overloaded functions; a cleaner casting utility. You must use this to emulate default parameters.
 
 .. _a basic example: https://github.com/ThePhD/sol2/blob/develop/examples/usertype.cpp

docs/source/tutorial/getting-started.rst

@@ -61,25 +61,23 @@ The second line opens a single lua-provided library, "base". There are several o
 
 If you're interested in integrating Sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example<existing>` to see how to work with Sol when you add it to a project (the existing example covers ``require`` as well)!
 
-Some more ways of loading scripts and handling errors is shown `in this example`_!
+.. note::
+
+	After you learn the basics of sol, it is usually advised that if you think something can work, you should TRY IT. It will probably work!
+	
+
+Some more ways of loading scripts and handling errors is shown `in this example`_! There is also a full, cross-platform `example of loading a DLL`_.
 
 Next, let's start :doc:`reading/writing some variables<variables>` from Lua into C++, and vice-versa!
 
 
 .. _vanilla Lua: https://www.lua.org/
-
 .. _LuaJIT: http://luajit.org/
-
 .. _GCC 6.0: https://gcc.gnu.org/gcc-6/changes.html
-
 .. _single header file release: https://github.com/ThePhD/sol2/releases
-
 .. _repository as well: https://github.com/ThePhD/sol2/blob/develop/single/sol/sol.hpp
-
 .. _single/sol/sol.hpp: https://github.com/ThePhD/sol2/blob/develop/single/sol/sol.hpp
-
 .. _github repository here: https://github.com/ThePhD/sol2
-
 .. _Lua page on getting started: https://www.lua.org/start.html
-
 .. _in this example: https://github.com/ThePhD/sol2/blob/develop/examples/basic.cpp
+.. _example of loading a DLL: https://github.com/ThePhD/sol2/tree/develop/examples/require_dll_example

docs/source/usertypes.rst

@@ -22,6 +22,7 @@ The examples folder also has a number of really great examples for you to see. T
 * You can use :doc:`filters<api/filters>` to control dependencies and streamline return values, as well as apply custom behavior to a functions return
 * You can work with special wrapper types such as ``std::unique_ptr<T>``, ``std::shared_ptr<T>``, and others by default
     - Extend them using the :doc:`sol::unique_usertype\<T\> traits<api/unique_usertype_traits>`
+    - This allows for custom smart pointers, special pointers, custom handles and others to be given certain handling semantics to ensure proper RAII with Lua's garbage collection
 * (Advanced) You can override the iteration function for Lua 5.2 and above (LuaJIT does not have the capability) `as shown in the pairs example`_
 * Please note that the colon is necessary to "automatically" pass the ``this``/``self`` argument to Lua methods
 	- ``obj:method_name()`` is how you call "member" methods in Lua
@@ -46,7 +47,7 @@ The examples folder also has a number of really great examples for you to see. T
 * Member methods, properties, variables and functions taking ``self&`` arguments modify data directly
 	- Work on a copy by taking arguments or returning by value.
 	- Do not use r-value references: they do not mean anything in Lua code.
-	- Move-only types can only be taken by reference: sol2 cannot know if/when to move a value (except when serializing with perfect forwarding *into* Lua)
+	- Move-only types can only be taken by reference: sol2 cannot know if/when to move a value (except when serializing with perfect forwarding *into* Lua, but not calling a C++ function from Lua)
 * The actual metatable associated with the usertype has a long name and is defined to be opaque by the Sol implementation.
 * The actual metatable inner workings is opaque and defined by the Sol implementation, and there are no internal docs because optimizations on the operations are applied based on heuristics we discover from performance testing the system.