From 2d89eb39da8e758e2a371f4d53989c91d22a5ba0 Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Fri, 26 Jan 2018 18:32:58 +0100 Subject: [PATCH 1/5] Don't use a `StdResult` alias for better docs. This is a pretty opinionated change, but I find documentation to be clearer when using plain old names everybody understands immediately. --- src/error.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/error.rs b/src/error.rs index 9145dbe..212077c 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,6 +1,5 @@ use std::fmt; use std::sync::Arc; -use std::result::Result as StdResult; use failure; @@ -112,7 +111,7 @@ pub enum Error { } /// A specialized `Result` type used by `rlua`'s API. -pub type Result = StdResult; +pub type Result = ::std::result::Result; impl fmt::Display for Error { fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result { @@ -203,7 +202,7 @@ pub trait ExternalResult { fn to_lua_err(self) -> Result; } -impl ExternalResult for StdResult +impl ExternalResult for ::std::result::Result where E: ExternalError, { From 67f8e1d49c4b2b8eb9884ed24fea3d3ad0b6a69e Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Fri, 26 Jan 2018 18:35:21 +0100 Subject: [PATCH 2/5] Fix rustdoc rendering warning --- src/error.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/error.rs b/src/error.rs index 212077c..9c17861 100644 --- a/src/error.rs +++ b/src/error.rs @@ -31,10 +31,11 @@ pub enum Error { /// This is an error because `rlua` callbacks are FnMut and thus can only be mutably borrowed /// once. RecursiveCallbackError, - /// Lua code has accessed a [`UserData`] value that was already garbage collected + /// Lua code has accessed a [`UserData`] value that was already garbage collected. /// /// This can happen when a [`UserData`] has a custom `__gc` metamethod, this method resurrects /// the [`UserData`], and then the [`UserData`] is subsequently accessed. + /// /// [`UserData`]: trait.UserData.html ExpiredUserData, /// A Rust value could not be converted to a Lua value. From 79b028419fc40ee751b7b6b1c724371c0b501d77 Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Fri, 26 Jan 2018 19:24:01 +0100 Subject: [PATCH 3/5] create_function docs: mention what returning `Err` does --- src/lua.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/lua.rs b/src/lua.rs index a7c55b1..1a03920 100644 --- a/src/lua.rs +++ b/src/lua.rs @@ -191,6 +191,15 @@ impl Lua { /// Wraps a Rust function or closure, creating a callable Lua function handle to it. /// + /// The function's return value is always a `Result`: If the function returns `Err`, the error + /// is raised as a Lua error, which can be caught using `(x)pcall` or bubble up to the Rust code + /// that invoked the Lua code. This allows using the `?` operator to propagate errors through + /// intermediate Lua code. + /// + /// If the function returns `Ok`, the contained value will be converted to one or more Lua + /// values. For details on Rust-to-Lua conversions, refer to the [`ToLua`] and [`ToLuaMulti`] + /// traits. + /// /// # Examples /// /// Create a function which prints its argument: @@ -232,6 +241,9 @@ impl Lua { /// # try_main().unwrap(); /// # } /// ``` + /// + /// [`ToLua`]: trait.ToLua.html + /// [`ToLuaMulti`]: trait.ToLuaMulti.html pub fn create_function<'lua, A, R, F>(&'lua self, mut func: F) -> Result> where A: FromLuaMulti<'lua>, From 0a4ae8d859a150eab29007c8579edea73521076b Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Fri, 26 Jan 2018 19:44:35 +0100 Subject: [PATCH 4/5] Additional `MetaMethod` docs --- src/userdata.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/userdata.rs b/src/userdata.rs index 98ec717..aac80df 100644 --- a/src/userdata.rs +++ b/src/userdata.rs @@ -11,6 +11,11 @@ use value::{FromLua, FromLuaMulti, ToLuaMulti}; use lua::Lua; /// Kinds of metamethods that can be overridden. +/// +/// For safety reasons, this mechanism does not allow overriding the `__gc` metamethod. [`UserData`] +/// implementors can instead just use `Drop`. +/// +/// [`UserData`]: trait.UserData.html #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)] pub enum MetaMethod { /// The `+` operator. @@ -57,7 +62,9 @@ pub enum MetaMethod { NewIndex, /// The call "operator" `obj(arg1, args2, ...)`. Call, - /// tostring(ud) will call this if it exists + /// The `__tostring` metamethod. + /// + /// This is not an operator, but will be called by methods such as `tostring` and `print`. ToString, } From ff847ea438651129b60377bbeff7d5bef1f9c6cf Mon Sep 17 00:00:00 2001 From: Jonas Schievink Date: Fri, 26 Jan 2018 21:31:01 +0100 Subject: [PATCH 5/5] __gc would be safe now, reword MetaMethod docs accordingly --- src/userdata.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/userdata.rs b/src/userdata.rs index aac80df..8474a6a 100644 --- a/src/userdata.rs +++ b/src/userdata.rs @@ -12,8 +12,8 @@ use lua::Lua; /// Kinds of metamethods that can be overridden. /// -/// For safety reasons, this mechanism does not allow overriding the `__gc` metamethod. [`UserData`] -/// implementors can instead just use `Drop`. +/// Currently, this mechanism does not allow overriding the `__gc` metamethod, since there is +/// generally no need to do so: [`UserData`] implementors can instead just implement `Drop`. /// /// [`UserData`]: trait.UserData.html #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]