[lua] very minor documentation pass for the only lua api function and…

… its c++ integration

doc/DoxygenLayout.xml

@@ -4,6 +4,7 @@
   <navindex>
     <tab type="mainpage" visible="yes" title="Topaz Home"/>
     <tab type="user" visible="yes" title="C++ API" url="@ref tz_cpp"/>
+    <tab type="user" visible="yes" title="Lua API" url="@ref tz_lua"/>
     <tab type="user" visible="yes" title="TZSL API" url="@ref tzsl"/>
     <tab type="user" visible="yes" title="Wiki" url="https://github.com/harrand/Topaz/wiki"/ target="_blank">
   </navindex>

src/tz/lua/lua.hpp

@@ -0,0 +1,19 @@
+#ifndef TOPAZ_LUA_LUA_HPP
+#define TOPAZ_LUA_LUA_HPP
+
+/**
+* @page tz_lua Lua API Reference
+* @section Functions
+* @code{.lua}
+* function tz.assert(expr: boolean)
+* @endcode
+* Asserts that an expression is true. If it is false, an assertion failure occurs on debug builds.
+*/
+
+/**
+* @ingroup tz_cpp
+* @defgroup tz_lua_cpp Lua Integration
+* Run Lua code from within Topaz C++. See @ref tz_lua for the Topaz-provided lua API.
+*/
+
+#endif // TOPAZ_LUA_LUA_HPP

src/tz/lua/state.hpp

@@ -4,18 +4,42 @@
 
 namespace tz::lua
 {
+	/**
+	* @ingroup tz_lua_cpp
+	* Represents a lua state. To retrieve the main lua state, see @ref tz::lua::get_state()
+	*/
 	class state
 	{
 	public:
 		state() = default;
 		state(void* lstate);
+		/**
+		* Query as to whether the state is valid.
+		* @return True if the state is valid, false otherwise.
+		*/
 		bool valid() const;
+		/**
+		* Attempt to execute a lua source file. The code is instantly executed, and returns on completion.
+		* @param path The relative path locating the lua source file (with extension).
+		* @param assert_on_failure Whether Topaz should assert on the code running without any errors.
+		* @return Whether the executed code experienced any errors.
+		*/
 		bool execute_file(const char* path, bool assert_on_failure = true) const;
+		/**
+		* Attempt to execute a lua source string. The code is instantly executed, and returns on completion.
+		* @param lua_src String containing lua source code, appropriate for the state.
+		* @param assert_on_failure Whether Topaz should assert on the code running without any errors.
+		* @return Whether the executed code experienced any errors.
+		*/
 		bool execute(const char* lua_src, bool assert_on_failure = true) const;
 	private:
 		void* lstate = nullptr;
 	};
 
+	/**
+	* @ingroup tz_lua_cpp
+	* Retrieve the main lua @ref tz::lua::state.
+	*/
 	state& get_state();
 }