documentation cleanup

docs/source/api/optional.rst

@@ -0,0 +1,4 @@
+optional
+========
+
+This is an implemention of `optional from the standard library`. If it detects that a proper optional exists, it will attempt to use it. This is mostly an implementation detail, used in the :ref:`stack::check_get<stack-check-get>` and :ref:`stack::get\<optional\<T>><stack-get>` and ``optional<T> maybe_value = table["arf"];`` impementations for additional safety reasons.

docs/source/api/proxy.rst

@@ -113,8 +113,16 @@ Gets the value associated with the keys the proxy was generated and convers it t
 
 Gets the value associated with the keys the proxy was generated and convers it to the type ``T``.
 
-proxy-only members
-------------------
+``operator[]`` proxy-only members
+---------------------------------
+
+.. code-block:: c++
+	:caption: function: validity
+	:name: proxy-valid
+
+	bool valid () const;
+
+Returns whether this proxy actually refers to a valid object.
 
 .. code-block:: c++
 	:caption: functions: [overloaded] implicit set

docs/source/api/stack.rst

@@ -21,7 +21,9 @@ functions
 	template <typename T>
 	auto get( lua_State* L, int index = -1 )
 
-Retrieves the value of the object at ``index`` in the stack. The return type varies based on ``T``: with primitive types, it is usually ``T``: for all unrecognized ``T``, it is generally a ``T&`` or whatever the extension point :ref:`stack::getter\<T><getter>` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\<T><getter>` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get<stack-check-get>` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :ref:`safety<safety>`.
+Retrieves the value of the object at ``index`` in the stack. The return type varies based on ``T``: with primitive types, it is usually ``T``: for all unrecognized ``T``, it is generally a ``T&`` or whatever the extension point :ref:`stack::getter\<T><getter>` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\<T><getter>` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get<stack-check-get>` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :doc:`safety<../safety>`.
+
+You may also retrieve an :doc:`sol::optional\<T><optional>` from this as well, to have it attempt to not throw errors when performing the get and the type is not correct.
 
 .. code-block:: cpp
 	:caption: function: check
@@ -35,6 +37,17 @@ Retrieves the value of the object at ``index`` in the stack. The return type var
 
 Checks if the object at ``index`` is of type ``T``. If it is not, it will call the ``handler`` function with ``lua_State*``, ``int index``, ``type`` expected, and ``type`` actual as arguments.
 
+.. code-block:: cpp
+	:caption: function: check_get
+	:name: stack-check-get
+
+	template <typename T>
+	auto check_get( lua_State* L, int index = -1 )
+	template <typename T, typename Handler>
+	auto check_get( lua_State* L, int index, Handler&& handler )
+
+Retrieves the value of the object at ``index`` in the stack, but does so safely. It returns an ``optional<U>``, where ``U`` in this case is the return type deduced from ``stack::get<T>``. This allows a person to properly check if the type they're getting is what they actually want, and gracefully handle errors when working with the stack if they so choose to. You can define ``SOL_CHECK_ARGUMENTS`` to turn on additional :doc:`safety<../safety>`, in which ``stack::get`` will default to calling this version of the function with a handler of ``type_panic`` to strongly alert for errors and help you track bugs if you suspect something might be going wrong in your system.
+
 .. code-block:: cpp
 	:caption: function: push
 	:name: stack-push
@@ -53,17 +66,6 @@ Checks if the object at ``index`` is of type ``T``. If it is not, it will call t
 
 Based on how it is called, pushes a variable amount of objects onto the stack. in 99% of cases, returns for 1 object pushed onto the stack. For the case of a ``std::tuple<...>``, it recursively pushes each object contained inside the tuple, from left to right, resulting in a variable number of things pushed onto the stack (this enables multi-valued returns when binding a C++ function to a Lua). Can be called with ``sol::stack::push<T>( L, args... )`` to have arguments different from the type that wants to be pushed, or ``sol::stack::push( L, arg, args... )`` where ``T`` will be inferred from ``arg``. The final form of this function is ``sol::stack::multi_push``, which will call one ``sol::stack::push`` for each argument. The ``T`` that describes what to push is first sanitized by removing top-level ``const`` qualifiers and reference qualifiers before being forwarded to the extension point :ref:`stack::pusher\<T><pusher>` struct.
 
-.. code-block:: cpp
-	:caption: function: check_get
-	:name: stack-check-get
-
-	template <typename T>
-	auto check_get( lua_State* L, int index = -1 )
-	template <typename T, typename Handler>
-	auto check_get( lua_State* L, int index, Handler&& handler )
-
-Retrieves the value of the object at ``index`` in the stack, but does so safely. It returns an ``optional<U>``, where ``U`` in this case is the return type deduced from ``stack::get<T>``. This allows a person to properly check if the type they're getting is what they actually want, and gracefully handle errors when working with the stack if they so choose to. You can define ``SOL_CHECK_ARGUMENTS`` to turn on additional :ref:`safety<safety>`, in which ``stack::get`` will default to calling this version of the function with a handler of ``type_panic`` to strongly alert for errors and help you track bugs if you suspect something might be going wrong in your system.
-
 .. code-block:: cpp
 	:caption: function: set_field
 

docs/source/api/top.rst

@@ -21,6 +21,7 @@ Browse the various function and classes :doc:`Sol<../index>` utilizes to make yo
    reference
    resolve
    stack
+   optional
    state
    table
    thread

docs/source/safety.rst

@@ -7,4 +7,4 @@ Sol was designed to be correct and fast, and in the pursuit of both uses the reg
 	* ``stack::get`` (used everywhere) defaults to using ``stack::check_get`` and dereferencing the argument. It uses ``type_panic`` as the handler if something goes wrong.
 	* ``stack::call`` will, if no template 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.
+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 :ref:`sol::optional\<T><optional>` when necessary.