fixing up da docs

docs/source/api/compatibility.rst

@@ -3,8 +3,12 @@ compatibility.hpp
 Lua 5.3/5.2 compatibility for Lua 5.1/LuaJIT
 --------------------------------------------
 
-This is a detail header used to maintain compatability with the 5.2 and 5.3 APIs. It contains code from the MIT-Licensed `Lua<http://www.Lua.org/>` code in some places and also from the `lua-compat<https://github.com/keplerproject/lua-compat-5.3>` repository by KeplerProject.
+This is a detail header used to maintain compatability with the 5.2 and 5.3 APIs. It contains code from the MIT-Licensed `Lua code`_ in some places and also from the `lua-compat`_ repository by KeplerProject.
 
-It is not fully documented as this header's only purpose is for internal use to make sure Sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker<https://github.com/ThePhD/sol2/issues/>`.
+It is not fully documented as this header's only purpose is for internal use to make sure Sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker`_.
 
 For the licenses, see :doc:`here<../licenses>`
+
+.. _issue in the issue tracker: https://github.com/ThePhD/sol2/issues/
+.. _Lua code: http://www.Lua.org/
+.. _lua-compat: https://github.com/keplerproject/lua-compat-5.3

docs/source/api/coroutine.rst

@@ -5,7 +5,7 @@ resumable/yielding functions from Lua
 
 A ``coroutine`` is a :doc:`reference<reference>` to a function in Lua that can be called multiple times to yield a specific result. It is run on the :doc:`lua_State<state>` that was used to create it (see :doc:`thread<thread>` for an example on how to get a coroutine that runs on a thread separate from your usual "main" :doc:`lua_State<state>`).
 
-The ``coroutine`` object is entirely similar to the :doc:`protected_function<protected_function>` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded<types>`) and is thus runnable again, whether it has completed (:doc:`call_status::ok<types>`) and thus cannot yield anymore values, or whether it has suffered an error (see `status()` and :doc:`call_status<types>`'s error codes).
+The ``coroutine`` object is entirely similar to the :doc:`protected_function<protected_function>` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded<types>`) and is thus runnable again, whether it has completed (:ref:`call_status::ok<call-status>`) and thus cannot yield anymore values, or whether it has suffered an error (see :ref:`status()<status>` and :ref:`call_status<call-status>`'s error codes).
 
 For example, you can work with a coroutine like this:
 
@@ -61,10 +61,9 @@ The following are the members of ``sol::coroutine``:
 members
 -------
 
-.. _status:
-
 .. code-block:: cpp
 	:caption: returning the coroutine's status
+	:name: status
 
 	call_status status() const noexcept;
 
@@ -100,4 +99,4 @@ These functions allow you to check if a coroutine can still be called (has more
 	template<typename... Ret, typename... Args>
 	decltype(auto) operator()( types<Ret...>, Args&&... args );
 
-Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types<int, std::string>, ...)`` syntax. Check :ref:`status()<status>` afterwards for more information about the success of the run or just check the coroutine object in an ifs tatement, as shown :ref:`above<runnable>`.
+Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types<int, std::string>, ...)`` syntax. Check ``status()`` afterwards for more information about the success of the run or just check the coroutine object in an ifs tatement, as shown :ref:`above<runnable>`.

docs/source/api/error.rst

@@ -10,6 +10,6 @@ the single 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 :doc:`sol::state<state>`. 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<state#set-panic>`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are :doc:`nil<types>`.
 
 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.

docs/source/api/function.rst

@@ -7,7 +7,7 @@ calling functions bound to Lua
 	
 	class function : public reference;
 
-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. 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:`function_result<proxy>` class that gets implicitly converted to the requested return type. For example:
+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. When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :ref:`function_result<proxy#function-result>` class that gets implicitly converted to the requested return type. For example:
 
 .. code-block:: lua
 	:caption: func_barks.lua

docs/source/api/proxy.rst

@@ -18,8 +18,6 @@ proxy, (protected\_)function_result - proxy_base derivatives
 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>`.
 
 
-.. _proxy:
-
 proxy
 -----
 
@@ -78,7 +76,8 @@ members
 -------
 
 .. code-block:: c++
-	:caption: [overloaded] implicit conversion get
+	:caption: functions: [overloaded] implicit conversion get
+	:name: implicit-get
 
 	requires( sol::is_primitive_type<T>::value == true )
 	template <typename T>
@@ -91,7 +90,8 @@ members
 Gets the value associated with the keys the proxy was generated and convers it to the type ``T``. Note that this function will always return ``T&``, a non-const reference, to types which are not based on :doc:`sol::reference<reference>` and not a :doc:`primitive lua type<types>`
 
 .. code-block:: c++
-	:caption: [overloaded] implicit set
+	:caption: functions: [overloaded] implicit set
+	:name: implicit-set
 
 	requires( sol::detail::Function<Fx> == false )
 	template <typename T>
@@ -104,6 +104,7 @@ Gets the value associated with the keys the proxy was generated and convers it t
 Sets the value associated with the keys the proxy was generated with to ``value``. If this is a function, calls ``set_function``. If it is not, just calls ``set``. See :ref:`note<note 1>`
 
 .. code-block:: c++
+	:caption: function: set a callable
 
 	template <typename Fx>
 	proxy& set_function( Fx&& fx );
@@ -111,6 +112,7 @@ Sets the value associated with the keys the proxy was generated with to ``value`
 Sets the value associated with the keys the proxy was generated with to a function ``fx``.
 
 .. code-block:: c++
+	:caption: function: get a value
 
 	template <typename T>
 	T get( ) const;
@@ -139,18 +141,19 @@ Consider the following:
 
 	sol::state lua;
 	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.
 
 
-.. _function_result:
+.. _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`` / templated ``operator=``.
 
-.. _protected_function_result:
+.. _protected-function-result:
 
 protected_function_result
 -------------------------

docs/source/api/state.rst

@@ -6,7 +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*>;
+	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.
 
@@ -15,10 +15,9 @@ The majority of the members between ``state_view`` and :doc:`sol::table<table>`
 enumerations
 ------------
 
-.. _libenum:
-
 .. code-block:: cpp
 	:caption: in-lua libraries
+	:name: lib-enum
 
 	enum class lib : char {
 	    base,
@@ -42,11 +41,12 @@ members
 
 .. code-block:: cpp
 	:caption: function: open standard libraries/modules
+	:name: open-libraries
 
 	template<typename... Args>
 	void open_libraries(Args&&... args);
 
-This function takes a number of :ref:`sol::lib<libenum>` as arguments and opens up the associated Lua core libraries. 
+This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens up the associated Lua core libraries. 
 
 .. code-block:: cpp
 	:caption: function: script / script_file
@@ -67,6 +67,7 @@ Get either the global table or the Lua registry as a :doc:`sol::table<table>`, w
 
 .. code-block:: cpp
 	:caption: function: Lua set_panic
+	:name: set-panic
 
 	void set_panic(lua_CFunction panic);
 

docs/source/api/types.rst

@@ -11,6 +11,7 @@ enumerations
 
 .. code-block:: cpp
 	:caption: syntax of a function called by Lua
+	:name: call-syntax
 	
 	enum class call_syntax {
     	dot = 0,
@@ -19,10 +20,9 @@ enumerations
 
 This enumeration indicates the syntax a function was called with in a specific scenario. There are two ways to call a function: with ``obj:func_name( ... )`` or ``obj.func_name( ... );`` The first one passes "obj" as the first argument: the second one does not. In the case of usertypes, this is used to determine whether the call to a :doc:`constructor/initializer<usertype>` was called with a ``:`` or a ``.``, and not misalign the arguments.
 
-.. _call_status:
-
 .. code-block:: cpp
 	:caption: status of a Lua function call
+	:name: call-status
 	
 	enum class call_status : int {
 	    ok      = LUA_OK,
@@ -35,10 +35,9 @@ This enumeration indicates the syntax a function was called with in a specific s
 
 This strongly-typed enumeration contains the errors potentially generated by a call to a :doc:`protected function<protected_function>` or a :doc:`coroutine<coroutine>`.
 
-.. _thread_status:
-
 .. code-block:: cpp
 	:caption: status of a Lua thread
+	:name: thread-status
 	
 	enum class thread_status : int {
 	    normal        = LUA_OK,
@@ -52,10 +51,9 @@ This strongly-typed enumeration contains the errors potentially generated by a c
 
 This enumeration contains the status of a thread. The ``thread_status::dead`` state is generated when the thread has nothing on its stack and it is not running anything.
 
-.. _type:
-
 .. code-block:: cpp
 	:caption: type enumeration
+	:name: type-enum
 
 	enum class type : int {
 	    none          = LUA_TNONE,
@@ -80,14 +78,16 @@ type traits
 
 .. code-block:: cpp
 	:caption: lua_type_of trait
+	:name: lua-type-of
 
 	template <typename T, typename = void>
 	struct lua_type_of;
 
-This type trait maps a C++ type to a :ref:`type enumation<type>` value. The default value is ``type::userdata``.
+This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. The default value is ``type::userdata``.
 
 .. code-block:: cpp
 	:caption: primitive checking traits
+	:name: is-primitive
 	
 	template <typename T>
 	struct is_lua_primitive;
@@ -104,6 +104,7 @@ special types
 -------------
 .. code-block:: cpp
 	:caption: nil
+	:name: nil
 
 	strunil_t {};
 	const nil_t nil {};
@@ -124,6 +125,7 @@ A tag type that, when used with :doc:`stack::get\<non_null\<T*>><stack>`, does n
 
 .. code-block:: cpp
 	:caption: type list
+	:name: type-list
 
 	template <typename... Args>
 	struct types;
@@ -165,7 +167,7 @@ These functions get the type of a C++ type ``T`` or the type at the specified in
 
 	std::string type_name(lua_State*L, type t);
 
-Gets the Lua-specified name of the :ref:`type<type>`.
+Gets the Lua-specified name of the :ref:`type<type-enum>`.
 
 structs
 -------

docs/source/features.rst

@@ -53,9 +53,12 @@ The Feature Matrix™
 The below feature table checks for the presence of something. It, however, does not actually account for any kind of laborious syntax.
 
 ✔ full support
-- partial support / wonky support
+
+~ partial support / wonky support
+
 ✗ no support
 
+
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
 |                           |   plain C   | luawrapper | lua-intf | luabind |  Selene  |    Sol    |   oolua   |   lua-api-pp   |  kaguya  |
 |                           |             |            |          |         |          |           |           |                |          |
@@ -66,33 +69,33 @@ The below feature table checks for the presence of something. It, however, does
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
 | arbitrary keys            |      ✔      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| user-defined types (udts) |      -      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     -     |        ✔       |     ✔    |
+| user-defined types (udts) |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| udts: member functions    |      -      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     -     |        ✔       |     ✔    |
+| udts: member functions    |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| udts: variables           |      -      |     -      |     -    |    -    |     -    |     ✔     |     -     |        -       |     -    |
+| udts: variables           |      ~      |     ~      |     ~    |    ~    |     ~    |     ✔     |     ~     |        ~       |     ~    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| stack abstractions        |      -      |     ✔      |     -    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |
+| stack abstractions        |      ~      |     ✔      |     ~    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| function binding          |      -      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |
+| function binding          |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| protected function        |      ✔      |     ✗      |     -    |    -    |     -    |     ✔     |     -     |        ✔       |     -    |
+| protected function        |      ✔      |     ✗      |     ~    |    ~    |     ~    |     ✔     |     ~     |        ✔       |     ~    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| multi-return              |      -      |     ✗      |     ✗    |    ✔    |     ✔    |     ✔     |     -     |        ✔       |     ✔    |
+| multi-return              |      ~      |     ✗      |     ✗    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| inheritance               |      -      |     ✗      |     ✗    |    ✔    |     ✔    |     ✔     |     -     |        -       |     ✔    |
+| inheritance               |      ~      |     ✗      |     ✗    |    ✔    |     ✔    |     ✔     |     ~     |        ~       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| overloading               |      -      |     ✗      |     ✗    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✗    |
+| overloading               |      ~      |     ✗      |     ✗    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✗    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
 | thread                    |      ✔      |     ✗      |     ✗    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
 | coroutines                |      ✔      |     ✗      |     ✗    |    ✔    |     ✔    |     ✔     |     ✗     |        ✗       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| no-rtti support           |      ✔      |     ✗      |     -    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |
+| no-rtti support           |      ✔      |     ✗      |     ~    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| no-exception support      |      ✔      |     ✗      |     -    |    -    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |
+| no-exception support      |      ✔      |     ✗      |     ~    |    ~    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
-| Lua 5.1                   |      ✔      |     ✔      |     -    |    ✔    |     ✗    |     ✔     |     ✔     |        ✔       |     ✔    |
+| Lua 5.1                   |      ✔      |     ✔      |     ~    |    ✔    |     ✗    |     ✔     |     ✔     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
 | Lua 5.2                   |      ✔      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+

docs/source/index.rst

@@ -8,27 +8,29 @@ Sol 2.0.0
 a fast, simple C++ and Lua Binding
 ----------------------------------
 
-Contents:
+When you need to hit the ground running with Lua and C++, `Sol`_ is the go-to framework for high-performance binding with an easy to use API.
----------
+
+get going:
+----------
 
 .. toctree::
    :maxdepth: 1
    :name: mastertoc
-   :caption: Contents
 	
+   api/top
    features
    benchmarks
    exceptions
    rtti
-   api/top
    licenses
 
+
 "I need feature X, maybe you have it?"
 --------------------------------------
-Take a look at the :doc:`Features<features>` page: it links to much of the API. Don't see a feature you want? Send inquiries for support for a particular abstraction to the `issues`_ tracker.
+Take a look at the :doc:`Features<features>` page: it links to much of the API. You can also just straight up browse the API. Don't see a feature you want? Send inquiries for support for a particular abstraction to the `issues`_ tracker.
 
 
-The Basics:
+the basics:
 -----------
 
 .. note::
@@ -96,8 +98,8 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 
-.. _issues: http://github.com/ThePhD/sol2/issues
+.. _Sol: https://github.com/ThePhD/sol2
+.. _issues: https://github.com/ThePhD/sol2/issues
 .. _examples directory: https://github.com/ThePhD/sol2/tree/develop/examples