From 2fee3e7891b7370ad83b9bdca14554f3a2d46bf3 Mon Sep 17 00:00:00 2001 From: Alex Orlenko Date: Thu, 25 Nov 2021 15:43:28 +0000 Subject: [PATCH] Update docs --- Cargo.toml | 2 +- README.md | 4 ++-- src/hook.rs | 8 ++++---- src/lib.rs | 19 ++++++++++++++++++- src/lua.rs | 34 ++++++++++++++++++---------------- src/stdlib.rs | 22 +++++++++++----------- src/table.rs | 5 +++-- src/thread.rs | 4 ++-- src/userdata.rs | 17 ++++++++--------- 9 files changed, 67 insertions(+), 48 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 4107d6c..34b7ead 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,7 +17,7 @@ with async/await features and support of writing native Lua modules in Rust. """ [package.metadata.docs.rs] -features = ["lua53", "async", "send", "serialize", "macros"] +features = ["lua54", "vendored", "async", "send", "serialize", "macros"] rustdoc-args = ["--cfg", "docsrs"] [workspace] diff --git a/README.md b/README.md index e65bee2..f585362 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,7 @@ fn main() -> LuaResult<()> { ``` ### Module mode -In a module mode `mlua` allows to create a compiled Lua module that can be loaded from Lua code using [`require`](https://www.lua.org/manual/5.3/manual.html#pdf-require). In this case `mlua` uses an external Lua runtime which could lead to potential unsafety due to unpredictability of the Lua environment and usage of libraries such as [`debug`](https://www.lua.org/manual/5.3/manual.html#6.10). +In a module mode `mlua` allows to create a compiled Lua module that can be loaded from Lua code using [`require`](https://www.lua.org/manual/5.4/manual.html#pdf-require). In this case `mlua` uses an external Lua runtime which could lead to potential unsafety due to unpredictability of the Lua environment and usage of libraries such as [`debug`](https://www.lua.org/manual/5.4/manual.html#6.10). [Example](examples/module) @@ -164,7 +164,7 @@ And then (**macOS** example): ``` sh $ cargo rustc -- -C link-arg=-undefined -C link-arg=dynamic_lookup $ ln -s ./target/debug/libmy_module.dylib ./my_module.so -$ lua5.3 -e 'require("my_module").hello("world")' +$ lua5.4 -e 'require("my_module").hello("world")' hello, world! ``` diff --git a/src/hook.rs b/src/hook.rs index ba2e507..bfb4873 100644 --- a/src/hook.rs +++ b/src/hook.rs @@ -11,9 +11,9 @@ use crate::lua::Lua; /// The `Debug` structure is provided as a parameter to the hook function set with /// [`Lua::set_hook`]. You may call the methods on this structure to retrieve information about the /// Lua code executing at the time that the hook function was called. Further information can be -/// found in the [Lua 5.3 documentation][lua_doc]. +/// found in the Lua [documentation][lua_doc]. /// -/// [lua_doc]: https://www.lua.org/manual/5.3/manual.html#lua_Debug +/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#lua_Debug /// [`Lua::set_hook`]: crate::Lua::set_hook pub struct Debug<'lua> { lua: &'lua Lua, @@ -171,10 +171,10 @@ pub struct DebugSource<'a> { pub struct DebugStack { pub num_ups: i32, /// Requires `feature = "lua54/lua53/lua52"` - #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))] + #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))] pub num_params: i32, /// Requires `feature = "lua54/lua53/lua52"` - #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))] + #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))] pub is_vararg: bool, } diff --git a/src/lib.rs b/src/lib.rs index 567873b..f89154a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -192,6 +192,23 @@ extern crate mlua_derive; #[cfg_attr(docsrs, doc(cfg(feature = "macros")))] pub use mlua_derive::chunk; -#[cfg(any(feature = "module"))] +/// Registers Lua module entrypoint. +/// +/// You can register multiple entrypoints as required. +/// +/// ``` +/// use mlua::{Lua, Result, Table}; +/// +/// #[mlua::lua_module] +/// fn my_module(lua: &Lua) -> Result { +/// let exports = lua.create_table()?; +/// exports.set("hello", "world")?; +/// Ok(exports) +/// } +/// ``` +/// +/// Internally in the code above the compiler defines C function `luaopen_my_module`. +/// +#[cfg(any(feature = "module", docsrs))] #[cfg_attr(docsrs, doc(cfg(feature = "module")))] pub use mlua_derive::lua_module; diff --git a/src/lua.rs b/src/lua.rs index 5ba90e2..1cf02e0 100644 --- a/src/lua.rs +++ b/src/lua.rs @@ -119,14 +119,14 @@ struct MemoryInfo { /// In Lua 5.4 GC can work in two modes: incremental and generational. /// Previous Lua versions support only incremental GC. /// -/// More information can be found in the Lua 5.x [documentation]. +/// More information can be found in the Lua [documentation]. /// /// [documentation]: https://www.lua.org/manual/5.4/manual.html#2.5 #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum GCMode { Incremental, /// Requires `feature = "lua54"` - #[cfg(any(feature = "lua54", doc))] + #[cfg(any(feature = "lua54"))] Generational, } @@ -144,8 +144,8 @@ pub struct LuaOptions { /// /// Default: **true** /// - /// [`pcall`]: https://www.lua.org/manual/5.3/manual.html#pdf-pcall - /// [`xpcall`]: https://www.lua.org/manual/5.3/manual.html#pdf-xpcall + /// [`pcall`]: https://www.lua.org/manual/5.4/manual.html#pdf-pcall + /// [`xpcall`]: https://www.lua.org/manual/5.4/manual.html#pdf-xpcall pub catch_rust_panics: bool, /// Max size of thread (coroutine) object cache used to execute asynchronous functions. @@ -157,6 +157,7 @@ pub struct LuaOptions { /// /// [`lua_resetthread`]: https://www.lua.org/manual/5.4/manual.html#lua_resetthread #[cfg(feature = "async")] + #[cfg_attr(docsrs, doc(cfg(feature = "async")))] pub thread_cache_size: usize, } @@ -188,6 +189,7 @@ impl LuaOptions { /// /// [`thread_cache_size`]: #structfield.thread_cache_size #[cfg(feature = "async")] + #[cfg_attr(docsrs, doc(cfg(feature = "async")))] pub const fn thread_cache_size(mut self, size: usize) -> Self { self.thread_cache_size = size; self @@ -616,7 +618,7 @@ impl Lua { /// /// Behavior is similar to Lua's [`require`] function. /// - /// [`require`]: https://www.lua.org/manual/5.3/manual.html#pdf-require + /// [`require`]: https://www.lua.org/manual/5.4/manual.html#pdf-require pub fn load_from_function<'lua, S, T>( &'lua self, modname: &S, @@ -935,7 +937,7 @@ impl Lua { /// Does not work on module mode where Lua state is managed externally. /// /// Requires `feature = "lua54/lua53/lua52"` - #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))] + #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))] pub fn set_memory_limit(&self, memory_limit: usize) -> Result { unsafe { match &mut (*self.extra.get()).mem_info { @@ -952,7 +954,7 @@ impl Lua { /// Returns true if the garbage collector is currently running automatically. /// /// Requires `feature = "lua54/lua53/lua52"` - #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))] + #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))] pub fn gc_is_running(&self) -> bool { let state = self.main_state.unwrap_or(self.state); unsafe { ffi::lua_gc(state, ffi::LUA_GCISRUNNING, 0) != 0 } @@ -1005,10 +1007,10 @@ impl Lua { /// Sets the 'pause' value of the collector. /// - /// Returns the previous value of 'pause'. More information can be found in the [Lua 5.3 - /// documentation][lua_doc]. + /// Returns the previous value of 'pause'. More information can be found in the Lua + /// [documentation][lua_doc]. /// - /// [lua_doc]: https://www.lua.org/manual/5.3/manual.html#2.5 + /// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5 pub fn gc_set_pause(&self, pause: c_int) -> c_int { let state = self.main_state.unwrap_or(self.state); unsafe { ffi::lua_gc(state, ffi::LUA_GCSETPAUSE, pause) } @@ -1017,9 +1019,9 @@ impl Lua { /// Sets the 'step multiplier' value of the collector. /// /// Returns the previous value of the 'step multiplier'. More information can be found in the - /// Lua 5.x [documentation][lua_doc]. + /// Lua [documentation][lua_doc]. /// - /// [lua_doc]: https://www.lua.org/manual/5.3/manual.html#2.5 + /// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5 pub fn gc_set_step_multiplier(&self, step_multiplier: c_int) -> c_int { let state = self.main_state.unwrap_or(self.state); unsafe { ffi::lua_gc(state, ffi::LUA_GCSETSTEPMUL, step_multiplier) } @@ -1028,7 +1030,7 @@ impl Lua { /// Changes the collector to incremental mode with the given parameters. /// /// Returns the previous mode (always `GCMode::Incremental` in Lua < 5.4). - /// More information can be found in the Lua 5.x [documentation][lua_doc]. + /// More information can be found in the Lua [documentation][lua_doc]. /// /// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5.1 pub fn gc_inc(&self, pause: c_int, step_multiplier: c_int, step_size: c_int) -> GCMode { @@ -1070,7 +1072,7 @@ impl Lua { /// Requires `feature = "lua54"` /// /// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5.2 - #[cfg(any(feature = "lua54", doc))] + #[cfg(any(feature = "lua54"))] pub fn gc_gen(&self, minor_multiplier: c_int, major_multiplier: c_int) -> GCMode { let state = self.main_state.unwrap_or(self.state); let prev_mode = @@ -2558,7 +2560,7 @@ pub enum ChunkMode { /// Trait for types [loadable by Lua] and convertible to a [`Chunk`] /// -/// [loadable by Lua]: https://www.lua.org/manual/5.3/manual.html#3.3.2 +/// [loadable by Lua]: https://www.lua.org/manual/5.4/manual.html#3.3.2 /// [`Chunk`]: crate::Chunk pub trait AsChunk<'lua> { /// Returns chunk data (can be text or binary) @@ -2571,7 +2573,7 @@ pub trait AsChunk<'lua> { /// Returns optional chunk [environment] /// - /// [environment]: https://www.lua.org/manual/5.3/manual.html#2.2 + /// [environment]: https://www.lua.org/manual/5.4/manual.html#2.2 fn env(&self, _lua: &'lua Lua) -> Result>> { Ok(None) } diff --git a/src/stdlib.rs b/src/stdlib.rs index 60c13c7..fb0f1b8 100644 --- a/src/stdlib.rs +++ b/src/stdlib.rs @@ -6,32 +6,32 @@ use std::u32; pub struct StdLib(u32); impl StdLib { - /// [`coroutine`](https://www.lua.org/manual/5.3/manual.html#6.2) library + /// [`coroutine`](https://www.lua.org/manual/5.4/manual.html#6.2) library /// /// Requires `feature = "lua54/lua53/lua52"` - #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))] + #[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))] pub const COROUTINE: StdLib = StdLib(1); - /// [`table`](https://www.lua.org/manual/5.3/manual.html#6.6) library + /// [`table`](https://www.lua.org/manual/5.4/manual.html#6.6) library pub const TABLE: StdLib = StdLib(1 << 1); - /// [`io`](https://www.lua.org/manual/5.3/manual.html#6.8) library + /// [`io`](https://www.lua.org/manual/5.4/manual.html#6.8) library pub const IO: StdLib = StdLib(1 << 2); - /// [`os`](https://www.lua.org/manual/5.3/manual.html#6.9) library + /// [`os`](https://www.lua.org/manual/5.4/manual.html#6.9) library pub const OS: StdLib = StdLib(1 << 3); - /// [`string`](https://www.lua.org/manual/5.3/manual.html#6.4) library + /// [`string`](https://www.lua.org/manual/5.4/manual.html#6.4) library pub const STRING: StdLib = StdLib(1 << 4); - /// [`utf8`](https://www.lua.org/manual/5.3/manual.html#6.5) library + /// [`utf8`](https://www.lua.org/manual/5.4/manual.html#6.5) library /// /// Requires `feature = "lua54/lua53"` - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] pub const UTF8: StdLib = StdLib(1 << 5); /// [`bit`](https://www.lua.org/manual/5.2/manual.html#6.7) library /// /// Requires `feature = "lua52/luajit"` #[cfg(any(feature = "lua52", feature = "luajit", doc))] pub const BIT: StdLib = StdLib(1 << 6); - /// [`math`](https://www.lua.org/manual/5.3/manual.html#6.7) library + /// [`math`](https://www.lua.org/manual/5.4/manual.html#6.7) library pub const MATH: StdLib = StdLib(1 << 7); - /// [`package`](https://www.lua.org/manual/5.3/manual.html#6.3) library + /// [`package`](https://www.lua.org/manual/5.4/manual.html#6.3) library pub const PACKAGE: StdLib = StdLib(1 << 8); /// [`jit`](http://luajit.org/ext_jit.html) library /// @@ -44,7 +44,7 @@ impl StdLib { /// Requires `feature = "luajit"` #[cfg(any(feature = "luajit", doc))] pub const FFI: StdLib = StdLib(1 << 30); - /// (**unsafe**) [`debug`](https://www.lua.org/manual/5.3/manual.html#6.10) library + /// (**unsafe**) [`debug`](https://www.lua.org/manual/5.4/manual.html#6.10) library pub const DEBUG: StdLib = StdLib(1 << 31); /// No libraries diff --git a/src/table.rs b/src/table.rs index 879a730..4f8c1bc 100644 --- a/src/table.rs +++ b/src/table.rs @@ -380,7 +380,7 @@ impl<'lua> Table<'lua> { /// ``` /// /// [`Result`]: crate::Result - /// [Lua manual]: http://www.lua.org/manual/5.3/manual.html#pdf-next + /// [Lua manual]: http://www.lua.org/manual/5.4/manual.html#pdf-next pub fn pairs, V: FromLua<'lua>>(self) -> TablePairs<'lua, K, V> { TablePairs { table: self.0, @@ -429,7 +429,7 @@ impl<'lua> Table<'lua> { /// /// [`pairs`]: #method.pairs /// [`Result`]: crate::Result - /// [Lua manual]: http://www.lua.org/manual/5.3/manual.html#pdf-next + /// [Lua manual]: http://www.lua.org/manual/5.4/manual.html#pdf-next pub fn sequence_values>(self) -> TableSequence<'lua, V> { TableSequence { table: self.0, @@ -514,6 +514,7 @@ pub trait TableExt<'lua> { /// /// The metamethod is called with the table as its first argument, followed by the passed arguments. #[cfg(feature = "async")] + #[cfg_attr(docsrs, doc(cfg(feature = "async")))] fn call_async<'fut, A, R>(&self, args: A) -> LocalBoxFuture<'fut, Result> where 'lua: 'fut, diff --git a/src/thread.rs b/src/thread.rs index 2f2297b..e805562 100644 --- a/src/thread.rs +++ b/src/thread.rs @@ -7,7 +7,7 @@ use crate::types::LuaRef; use crate::util::{check_stack, error_traceback, pop_error, StackGuard}; use crate::value::{FromLuaMulti, ToLuaMulti}; -#[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored"), doc))] +#[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored")))] use crate::function::Function; #[cfg(feature = "async")] @@ -182,7 +182,7 @@ impl<'lua> Thread<'lua> { /// /// [Lua 5.4]: https://www.lua.org/manual/5.4/manual.html#lua_resetthread /// [LuaJIT]: https://github.com/openresty/luajit2#lua_resetthread - #[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored"), doc))] + #[cfg(any(feature = "lua54", all(feature = "luajit", feature = "vendored")))] pub fn reset(&self, func: Function<'lua>) -> Result<()> { let lua = self.0.lua; unsafe { diff --git a/src/userdata.rs b/src/userdata.rs index b28d8cb..bf0706c 100644 --- a/src/userdata.rs +++ b/src/userdata.rs @@ -54,29 +54,29 @@ pub enum MetaMethod { Unm, /// The floor division (//) operator. /// Requires `feature = "lua54/lua53"` - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] IDiv, /// The bitwise AND (&) operator. /// Requires `feature = "lua54/lua53"` - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] BAnd, /// The bitwise OR (|) operator. /// Requires `feature = "lua54/lua53"` - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] BOr, /// The bitwise XOR (binary ~) operator. /// Requires `feature = "lua54/lua53"` - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] BXor, /// The bitwise NOT (unary ~) operator. /// Requires `feature = "lua54/lua53"` - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] BNot, /// The bitwise left shift (<<) operator. - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] Shl, /// The bitwise right shift (>>) operator. - #[cfg(any(feature = "lua54", feature = "lua53", doc))] + #[cfg(any(feature = "lua54", feature = "lua53"))] Shr, /// The string concatenation operator `..`. Concat, @@ -108,7 +108,6 @@ pub enum MetaMethod { feature = "lua53", feature = "lua52", feature = "luajit52", - doc ))] Pairs, /// The `__ipairs` metamethod. @@ -130,7 +129,7 @@ pub enum MetaMethod { /// Requires `feature = "lua54"` /// /// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#3.3.8 - #[cfg(any(feature = "lua54", doc))] + #[cfg(any(feature = "lua54"))] Close, /// A custom metamethod. ///