From 6bc034c5a90326c96cedff694167d924ee483873 Mon Sep 17 00:00:00 2001 From: ThePhD Date: Tue, 28 Mar 2017 22:13:08 -0400 Subject: [PATCH] [ci-skip] update usertype docs so I have somewhere to point users when they make a derp --- docs/source/features.rst | 2 +- docs/source/safety.rst | 4 +++- docs/source/usertypes.rst | 8 +++++++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/source/features.rst b/docs/source/features.rst index 1e942ef2..c3370343 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -10,7 +10,7 @@ For the hard technical components of Lua and its ecosystem we support, here is t what Sol supports ----------------- -* Support for Lua 5.1, 5.2, and 5.3. We achieve this through our :doc:`compatibility` header. +* Support for Lua 5.1, 5.2, and 5.3. We achieve this through our :doc:`compatibility` header. * :doc:`Table` support: setting values, getting values of multiple (different) types - :doc:`Lazy evaluation` for nested/chained queries diff --git a/docs/source/safety.rst b/docs/source/safety.rst index f9baac55..77e3af80 100644 --- a/docs/source/safety.rst +++ b/docs/source/safety.rst @@ -3,6 +3,8 @@ 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: + config ------ @@ -41,4 +43,4 @@ As a side note, binding functions with default parameters does not magically bin .. warning:: - Do NOT save the return type of a :ref:`function_result` with ``auto``, as in ``auto numwoof = woof(20);``, and do NOT store it anywhere. See :ref:`here`. \ No newline at end of file + Do NOT save the return type of a :ref:`function_result` with ``auto``, as in ``auto numwoof = woof(20);``, and do NOT store it anywhere. See :ref:`here`. diff --git a/docs/source/usertypes.rst b/docs/source/usertypes.rst index 01675d37..c3deafda 100644 --- a/docs/source/usertypes.rst +++ b/docs/source/usertypes.rst @@ -13,6 +13,12 @@ To learn more about usertypes, visit: The examples folder also has a number of really great examples for you to see. There are also some notes about guarantees you can find about usertypes, and their associated userdata, below: * All usertypes are runtime extensible in both `Lua`_ and `C++`_ +* Please note that the semi-colon is necessary to "automatically" pass the ``this``/``self`` argument to Lua methods + - ``obj:method_name()`` is how you call "member" methods in Lua + - It is purely syntactic sugar that passes the object name as the first argument to the ``method_name`` function + - ``my_obj:foo(bar, baz)`` is the same as ``my_obj.foo(my_obj, bar, baz)`` + - **Please note** that one uses a semi-colon, and the other uses a dot, and forgetting to do this properly will crash your code + - There are safety defines outlined in the :ref:`safety page here` * You can push types classified as userdata before you register a usertype. - You can register a usertype with the Lua runtime at any time sol2 - You can retrieve them from the Lua runtime as well through sol2 @@ -30,6 +36,6 @@ The examples folder also has a number of really great examples for you to see. T * Containers get pushed as special usertypes, but can be disabled if problems arise as detailed :doc:`here`. * You can use bitfields but it requires some finesse on your part. We have an example to help you get started `here, that uses a few tricks`_. -.. _here that uses a few tricks: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_bitfields.cpp +.. _here, that uses a few tricks: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_bitfields.cpp .. _Lua: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_advanced.cpp#L81 .. _C++: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_simple.cpp#L51 \ No newline at end of file