Add docs for everything, Make cstr, try_cstr properly return CString instead of dangling ptr

Wanted to make an elegant solution that would somehow make the pointer keep the value allocated, but I don't know enough about the standard library on how to do that. (I could std::mem::forget but that would just be awful)

Added docs for interfaces, lua_shared functions, types, global constants. Includes more example code.

Author: vurvdev

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "rglua"
 description = "Rust tooling for garrysmod development with the LuaJIT api"
-version = "0.7.0"
+version = "0.7.1"
 authors = ["Vurv <[email protected]>"]
 keywords = ["glua", "garrysmod", "lua", "gmod"]
 readme = "README.md"

src/globals.rs

@@ -3,10 +3,15 @@ use crate::types::*;
 pub mod Lua {
 	use super::c_int;
 
+	/// Index of the lua registry. What you'd get from debug.getregistry()
 	pub static REGISTRYINDEX: c_int = -10000;
+	/// Index of the lua environment.
+	/// This is like getfenv() or _ENV in later lua versions
 	pub static ENVIRONINDEX: c_int = -10001;
+	/// Index of _G
 	pub static GLOBALSINDEX: c_int = -10002;
 
+	/// Number of returns to use in functions like lua_pcall to represent 0 or more.
 	pub static MULTRET: c_int = -1;
 
 	pub static NUMTYPES: c_int = 9;

src/interface/mod.rs

@@ -15,13 +15,25 @@ pub use lua::{ILuaInterface, CLuaShared};
 pub use panel::{IPanel};
 
 use crate::try_cstr;
-use std::ffi::{c_void, CString};
+use std::ffi::c_void;
 use libloading::{Library, Symbol};
 
 pub type CreateInterfaceFn = extern "system" fn(pName: *const i8, pReturnCode: *mut i32) -> *mut c_void;
 
-///  # Safety
-/// This function is unsafe to transmute the internal libloading symbol to a proper createinterface function pointer.
+/// Gets a handle to provided source interface
+/// # Arguments
+/// * `file` - Filename of the interface dll, linked to gmod. For example "engine.dll"
+/// # Safety
+/// This function internally gets the symbol to the CreateInterface function and casts it to the desired interface provided
+/// So make sure you pass the correct interface type and a valid dll.
+/// # Examples
+/// ```rust, no_run
+/// use rglua::interface::get_interface_handle;
+/// unsafe {
+/// 	let vgui = get_interface_handle("vgui2.dll")
+/// 		.expect("Couldn't link to vgui2.dll");
+/// };
+/// ```
 pub unsafe fn get_interface_handle(file: &str) -> Result<CreateInterfaceFn, libloading::Error> {
 	let lib = Library::new(file)?;
 	let sym: Symbol<CreateInterfaceFn> = lib.get(b"CreateInterface\0")?;
@@ -39,6 +51,37 @@ pub enum InterfaceError {
 	FactoryNotFound,
 }
 
+/// Tries to get source interface from given interface name, and handle to it acquired from [get_interface_handle]
+/// # Arguments
+/// * `iface` - name of the interface to get, for example "VGUI_Panel009"
+/// * `factory` - handle to the interface, acquired from [get_interface_handle]
+/// # Examples
+/// Getting the raw PaintTraverse function from vgui:
+/// ```no_run
+/// // Wrappers to these interfaces are already provided but they do not give raw function pointers which is needed to detour / modify the functions
+/// // in any way, which you may want to do here, especially for painttraverse since you can safely run lua here if you queue it from a thread to avoid crashes.
+/// use rglua::interface::{get_interface_handle, get_from_interface, IPanel};
+/// type PaintTraverseFn = extern "fastcall" fn(&'static IPanel, usize, bool, bool);
+/// let handle = unsafe { get_interface_handle("vgui2.dll").unwrap() };
+///
+/// let vgui_interface = get_from_interface("VGUI_Panel009", handle)
+/// 	.unwrap() as *mut IPanel;
+///
+/// unsafe {
+/// 	// Use as_ref to access fields of the interface
+///		let panel_iface = vgui_interface
+/// 		.as_ref() // Unsafe as Rust doesn't know whether the interface is really valid or not
+/// 		.unwrap();
+///
+///
+/// 	// Transmute the function address from the offset into our known signature
+/// 	let paint_traverse: PaintTraverseFn = std::mem::transmute(
+/// 		(panel_iface.vtable as *mut *mut std::ffi::c_void)
+/// 			.offset(41) // vtable offset as seen in [interface/panel.rs]
+/// 			.read()
+/// 	);
+/// }
+/// ```
 pub fn get_from_interface(
 	iface: &str,
 	factory: CreateInterfaceFn,
@@ -47,7 +90,7 @@ pub fn get_from_interface(
 
 	let iface = try_cstr!(iface)?;
 
-	let result = factory(iface, &mut status);
+	let result = factory(iface.as_ptr(), &mut status);
 
 	if status == 0 && !result.is_null() {
 		Ok(result as *mut ())

src/interface/panel.rs

@@ -11,5 +11,7 @@ impl IPanel {
 	pub fn GetName(&self, vguiPanel: u32) -> *const i8 {}
 
 	#[virtual_index(41)]
+	/// PaintTraverse function, notorious for getting you banned from every other source engine game.
+	/// Lua runs properly here, so maybe you'd want to detour this.
 	pub fn PaintTraverse(&self, vguiPanel: u32, forceRepaint: bool, allowForce: bool) {}
 }

src/lua_shared/raw.rs

@@ -11,6 +11,7 @@ macro_rules! dyn_symbols {
 		$(#[$outer:meta])*
 		$vis:vis extern $abi:literal fn $name:ident ( $($arg:ident : $argty:ty),* $(,)? ) -> $ret:ty; $($rest:tt)*
 	) => {
+		$(#[$outer])*
 		pub static $name: Lazy<extern $abi fn( $($arg: $argty),* ) -> $ret> = Lazy::new(|| unsafe {
 			std::mem::transmute( LUA_SHARED_RAW.get::<extern $abi fn($($argty),*) -> $ret>( stringify!($name).as_bytes() ).unwrap() )
 		});
@@ -26,6 +27,7 @@ macro_rules! lua_macros {
 		$vis:vis fn $name:ident ( $($arg:ident : $argty:ty),* $(,)? ) -> $ret:ty $body:block; $($rest:tt)*
 	) => {
 		#[inline(always)]
+		$(#[$outer])*
 		$vis fn $name( $($arg: $argty),* ) -> $ret $body
 		lua_macros!( $($rest)* );
 	};
@@ -35,8 +37,6 @@ macro_rules! lua_macros {
 
 // Create Lazy cells that'll find the functions at runtime when called.
 dyn_symbols! {
-	pub extern "system" fn CreateInterface(pName: LuaString, pReturnCode: *mut c_int) -> *mut c_void;
-
 	pub extern "C" fn luaL_loadbufferx(
 		L: LuaState,
 		code: LuaString,
@@ -110,7 +110,10 @@ dyn_symbols! {
 	pub extern "C" fn lua_pushinteger(L: LuaState, n: LuaInteger) -> ();
 
 	// Type checking getters
+	/// Same as luaL_checknumber, but casts it to an integer.
 	pub extern "C" fn luaL_checkinteger(L: LuaState, narg: c_int) -> LuaInteger;
+	/// Checks whether the value at stack index 'narg' is a number and returns this number.
+	/// If it is not a lua number, will throw an error to Lua.
 	pub extern "C" fn luaL_checknumber(L: LuaState, narg: c_int) -> LuaNumber;
 	pub extern "C" fn luaL_checklstring(L: LuaState, narg: c_int, len: SizeT) -> LuaString;
 
@@ -125,7 +128,9 @@ dyn_symbols! {
 	pub extern "C" fn lua_createtable(L: LuaState, narr: c_int, nrec: c_int) -> ();
 
 	// Destruction
-	pub extern "C" fn lua_close(L: LuaState) -> (); // Destroys the lua state
+	/// Destroys the given lua state.
+	/// You *probably* don't want to do this, unless you just want to self destruct the server / your client.
+	pub extern "C" fn lua_close(L: LuaState) -> ();
 
 	// JIT
 	// Returns 1 for success, 0 for failure
@@ -148,6 +153,8 @@ dyn_symbols! {
 	// Coroutines
 	pub extern "C" fn lua_yield(L: LuaState, nresults: c_int) -> c_int;
 	pub extern "C" fn lua_status(L: LuaState) -> c_int;
+	/// Starts and resumes a coroutine in a given thread.
+	/// Blame garry for the _real
 	pub extern "C" fn lua_resume_real(L: LuaState, narg: c_int) -> c_int;
 
 	// Comparison
@@ -161,22 +168,32 @@ dyn_symbols! {
 	pub extern "C" fn lua_error(L: LuaState) -> c_int;
 
 	// Libraries
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaopen_table(L: LuaState) -> c_int;
+	/// Opens the standard 'string' library for a lua state
 	pub extern "C" fn luaopen_string(L: LuaState) -> c_int;
+	/// Opens the standard 'package' library for a lua state
 	pub extern "C" fn luaopen_package(L: LuaState) -> c_int;
+	/// Opens the standard 'os' library for a lua state
 	pub extern "C" fn luaopen_os(L: LuaState) -> c_int;
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaopen_math(L: LuaState) -> c_int;
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaopen_jit(L: LuaState) -> c_int;
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaopen_debug(L: LuaState) -> c_int;
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaopen_bit(L: LuaState) -> c_int;
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaopen_base(L: LuaState) -> c_int;
+	/// Opens the standard 'table' library for a lua state
 	pub extern "C" fn luaL_openlibs(L: LuaState) -> ();
+	/// Internally called by luaL_register, opens given list of LuaRegs with number of functions provided explicitly
 	pub extern "C" fn luaL_openlib(L: LuaState, libname: LuaString, l: *const LuaReg, nup: c_int) -> ();
 
-	/// luaL_register
 	/// When called with libname as nullptr, it simply registers all functions in the list l reg! into the table on the top of the stack.
 	/// # Example
-	/// ```rust
+	/// ```rust, ignore
 	/// let lib = reg! [
 	///     "my_function" => my_function,
 	///     "my_other_function" => my_other_function,
@@ -226,6 +243,7 @@ dyn_symbols! {
 	) -> LuaString;
 
 	pub extern "C" fn lua_checkstack(L: LuaState, extra: c_int) -> c_int;
+	/// Sets the error handler for the lua state.
 	pub extern "C" fn lua_atpanic(L: LuaState, panicf: LuaCFunction) -> LuaCFunction;
 	pub extern "C" fn lua_gettop(L: LuaState) -> c_int;
 	pub extern "C" fn lua_remove(L: LuaState, index: c_int) -> ();
@@ -235,39 +253,51 @@ dyn_symbols! {
 	pub extern "C" fn luaL_prepbuffer(b: *mut LuaBuffer) -> *mut i8;
 
 	// String methods
+	/// Creates a copy of string 's' by replacing any occurrence of the string 'p' with the string 'r'
+	/// Pushes the resulting string on the stack and returns it
 	pub extern "C" fn luaL_gsub(s: LuaString, pattern: LuaString, replace: LuaString) -> LuaString;
 }
 
 // Inline functions to mirror the C macros that come with the lua api
 lua_macros! {
+	/// Pops n elements from the lua stack.
 	pub fn lua_pop(L: LuaState, ind: c_int) -> () {
 		lua_settop(L, -(ind) - 1);
 	};
 
+	/// Gets a value from _G
+	/// Internally calls lua_getfield with [crate::globals::Lua::GLOBALSINDEX]
 	pub fn lua_getglobal(L: LuaState, name: LuaString) -> () {
 		lua_getfield(L, GLOBALSINDEX, name);
 	};
 
+	/// Sets a value in _G
+	/// Internally calls lua_setfield with [crate::globals::Lua::GLOBALSINDEX]
 	pub fn lua_setglobal(L: LuaState, name: LuaString) -> () {
 		lua_setfield(L, GLOBALSINDEX, name);
 	};
 
+	/// Pushes a "C" function to the stack
 	pub fn lua_pushcfunction(L: LuaState, fnc: LuaCFunction) -> () {
 		lua_pushcclosure(L, fnc, 0);
 	};
 
+	/// Equivalent to lua_tolstring with len equal to 0
 	pub fn lua_tostring(L: LuaState, idx: c_int) -> LuaString {
 		lua_tolstring(L, idx, 0)
 	};
 
+	/// Starts and resumes a coroutine in a given thread
 	pub fn lua_resume(L: LuaState, narg: c_int) -> c_int {
 		lua_resume_real(L, narg)
 	};
 
+	/// Returns if the value at the given index is a C or Lua function.
 	pub fn lua_isfunction(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) == Lua::Type::Function
 	};
 
+	/// Returns if the value at the given index is a table.
 	pub fn lua_istable(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) == Lua::Type::Table
 	};
@@ -276,44 +306,59 @@ lua_macros! {
 		lua_type(L, n) == Lua::Type::LUserData
 	};
 
+	/// Returns if the value at the given index is nil.
+	/// You might want to use [lua_isnoneornil] instead.
 	pub fn lua_isnil(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) == Lua::Type::Nil
 	};
 
+	/// Returns if the value at the given index is a boolean.
 	pub fn lua_isboolean(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) == Lua::Type::Bool
 	};
 
+	/// Returns if the value at the given index is a thread.
 	pub fn lua_isthread(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) == Lua::Type::Thread
 	};
 
+	/// Returns if the value at the given index is none (element outside of stack / invalid)
 	pub fn lua_isnone(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) == Lua::Type::None
 	};
 
+	/// Returns if the value at the given index is none (invalid) or nil.
 	pub fn lua_isnoneornil(L: LuaState, n: c_int) -> bool {
 		lua_type(L, n) <= 0
 	};
 
+	/// Loads and pcalls a string of lua code
+	/// Returns if the code was successfully executed
+	/// Error will be left on the stack if the code failed to execute
 	pub fn luaL_dostring(L: LuaState, str: LuaString) -> bool {
 		luaL_loadstring(L, str) == 0 || lua_pcall(L, 0, Lua::MULTRET, 0) == 0
 	};
 
+	/// Loads and pcalls a file's lua code
+	/// Returns if the code was successfully executed
+	/// Error will be left on the stack if the code failed to execute
 	pub fn luaL_dofile(L: LuaState, filename: LuaString) -> bool {
 		luaL_loadfile(L, filename) == 0 || lua_pcall(L, 0, Lua::MULTRET, 0) == 0
 	};
 
+	/// Returns value at [crate::globals::Lua::REGISTRYINDEX] with name 'name'
 	pub fn luaL_getmetatable(L: LuaState, name: LuaString) -> () {
 		lua_getfield(L, Lua::REGISTRYINDEX, name);
 	};
 
+	/// If a condition is false, throws an argument error at numarg
 	pub fn luaL_argcheck(L: LuaState, cond: bool, numarg: c_int, extramsg: LuaString) -> () {
 		if !cond {
 			luaL_argerror(L, numarg, extramsg);
 		}
 	};
 
+	/// Returns the type name of object at index i
 	pub fn luaL_typename(L: LuaState, i: c_int) -> LuaString {
 		lua_typename(L, lua_type(L, i))
 	};

src/types.rs

@@ -6,12 +6,20 @@ pub type LuaString = *const ffi::c_char; // const i8
 pub type SizeT = usize;
 
 // Lua Types below
-pub type LuaNumber = f64; // All lua numbers are doubles in Lua 5.1 (Glua)
+
+/// All lua numbers < Lua 5.3 are doubles (float 64). GLua is no different as it runs on LuaJIT which mimics 5.1
+pub type LuaNumber = f64;
 pub type LuaInteger = isize;
 
+/// This is not an actual lua state, in fact it's just a pointer to it.
+/// However you will never have ownership of a lua state here, so I opted to make the type follow suit.
 pub type LuaState = *mut c_void; // Raw Lua state.
+
+/// Lua "C" Functions are C ABI functions that return the number returns that will be passed to the Lua stack.
 pub type LuaCFunction = extern "C" fn(LuaState) -> c_int;
 
+/// luaL_Reg type, used for defining large amounts of functions with names to be -
+/// registered into lua with luaL_register / openlibs.
 #[repr(C)]
 pub struct LuaReg {
 	pub name: *const i8, // c_schar