From cd1e08522417ba4cf69b56ad8c1a623481578b8a Mon Sep 17 00:00:00 2001 From: ThePhD Date: Fri, 25 Mar 2016 10:58:33 -0400 Subject: [PATCH] documentation cleanup --- docs/source/api/optional.rst | 4 ++++ docs/source/api/proxy.rst | 12 ++++++++++-- docs/source/api/stack.rst | 26 ++++++++++++++------------ docs/source/api/top.rst | 1 + docs/source/safety.rst | 2 +- 5 files changed, 30 insertions(+), 15 deletions(-) create mode 100644 docs/source/api/optional.rst diff --git a/docs/source/api/optional.rst b/docs/source/api/optional.rst new file mode 100644 index 00000000..d75c0f01 --- /dev/null +++ b/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` and :ref:`stack::get\>` and ``optional maybe_value = table["arf"];`` impementations for additional safety reasons. \ No newline at end of file diff --git a/docs/source/api/proxy.rst b/docs/source/api/proxy.rst index ea62fbb2..cd08f19f 100644 --- a/docs/source/api/proxy.rst +++ b/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 diff --git a/docs/source/api/stack.rst b/docs/source/api/stack.rst index 381f02af..7231fdbe 100644 --- a/docs/source/api/stack.rst +++ b/docs/source/api/stack.rst @@ -21,7 +21,9 @@ functions template 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\` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :ref:`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\` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`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\` 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 + auto check_get( lua_State* L, int index = -1 ) + template + 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``, where ``U`` in this case is the return type deduced from ``stack::get``. 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( 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\` struct. -.. code-block:: cpp - :caption: function: check_get - :name: stack-check-get - - template - auto check_get( lua_State* L, int index = -1 ) - template - 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``, where ``U`` in this case is the return type deduced from ``stack::get``. 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`, 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 diff --git a/docs/source/api/top.rst b/docs/source/api/top.rst index 6b06b600..8f5981c1 100644 --- a/docs/source/api/top.rst +++ b/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 diff --git a/docs/source/safety.rst b/docs/source/safety.rst index 33a1ee49..3cb66fae 100644 --- a/docs/source/safety.rst +++ b/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. \ No newline at end of file +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\` when necessary. \ No newline at end of file