Merge pull request #66 from jonas-schievink/docs

Clarify a few docs

src/error.rs

@@ -1,6 +1,5 @@
 use std::fmt;
 use std::sync::Arc;
-use std::result::Result as StdResult;
 
 use failure;
 
@@ -32,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.
@@ -112,7 +112,7 @@ pub enum Error {
 }
 
 /// A specialized `Result` type used by `rlua`'s API.
-pub type Result<T> = StdResult<T, Error>;
+pub type Result<T> = ::std::result::Result<T, Error>;
 
 impl fmt::Display for Error {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
@@ -203,7 +203,7 @@ pub trait ExternalResult<T> {
     fn to_lua_err(self) -> Result<T>;
 }
 
-impl<T, E> ExternalResult<T> for StdResult<T, E>
+impl<T, E> ExternalResult<T> for ::std::result::Result<T, E>
 where
     E: ExternalError,
 {

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<Function<'lua>>
     where
         A: FromLuaMulti<'lua>,

src/userdata.rs

@@ -11,6 +11,11 @@ use value::{FromLua, FromLuaMulti, ToLuaMulti};
 use lua::Lua;
 
 /// Kinds of metamethods that can be overridden.
+///
+/// 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)]
 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,
 }