More documentation work

src/ffi.rs

@@ -1,3 +1,5 @@
+//! Bindings to the Lua 5.3 C API.
+
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]
 

src/lib.rs

@@ -1,4 +1,43 @@
-// Deny warnings inside doc tests / examples
+//! # High-level bindings to Lua
+//!
+//! The `rlua` crate provides safe high-level bindings to the [Lua programming language].
+//!
+//! # The `Lua` object
+//!
+//! The main type exported by this library is the [`Lua`] struct. In addition to methods for
+//! [executing] Lua chunks or [evaluating] Lua expressions, it provides methods for creating Lua
+//! values and accessing the table of [globals].
+//!
+//! # Converting data
+//!
+//! The [`ToLua`] and [`FromLua`] traits allow conversion from Rust types to Lua values and vice
+//! versa. They are implemented for many data structures found in Rust's standard library.
+//!
+//! For more general conversions, the [`ToLuaMulti`] and [`FromLuaMulti`] traits allow converting
+//! between Rust types and *any number* of Lua values.
+//!
+//! Most code in `rlua` is generic over implementors of those traits, so in most places the normal
+//! Rust data structures are accepted without having to write any boilerplate.
+//!
+//! # Custom Userdata
+//!
+//! The [`UserData`] trait can be implemented by user-defined types to make them available to Lua.
+//! Methods and operators to be used from Lua can be added using the [`UserDataMethods`] API.
+//!
+//! [Lua programming language]: https://www.lua.org/
+//! [`Lua`]: struct.Lua.html
+//! [executing]: struct.Lua.html#method.exec
+//! [evaluating]: struct.Lua.html#method.eval
+//! [globals]: struct.Lua.html#method.globals
+//! [`ToLua`]: trait.ToLua.html
+//! [`FromLua`]: trait.FromLua.html
+//! [`ToLuaMulti`]: trait.ToLuaMulti.html
+//! [`FromLuaMulti`]: trait.FromLuaMulti.html
+//! [`UserData`]: trait.UserData.html
+//! [`UserDataMethods`]: struct.UserDataMethods.html
+
+// Deny warnings inside doc tests / examples. When this isn't present, rustdoc doesn't show *any*
+// warnings at all.
 #![doc(test(attr(deny(warnings))))]
 
 extern crate libc;

src/lua.rs

@@ -85,6 +85,7 @@ pub trait FromLua<'lua>: Sized {
 pub struct MultiValue<'lua>(VecDeque<Value<'lua>>);
 
 impl<'lua> MultiValue<'lua> {
+    /// Creates an empty `MultiValue` containing no values.
     pub fn new() -> MultiValue<'lua> {
         MultiValue(VecDeque::new())
     }
@@ -436,6 +437,9 @@ impl<'lua> Table<'lua> {
         }
     }
 
+    /// Returns a reference to the metatable of this table, or `None` if no metatable is set.
+    ///
+    /// Unlike the `getmetatable` Lua function, this method ignores the `__metatable` field.
     pub fn get_metatable(&self) -> Option<Table<'lua>> {
         let lua = self.0.lua;
         unsafe {
@@ -454,6 +458,10 @@ impl<'lua> Table<'lua> {
         }
     }
 
+    /// Sets or removes the metatable of this table.
+    ///
+    /// If `metatable` is `None`, the metatable is removed (if no metatable is set, this does
+    /// nothing).
     pub fn set_metatable(&self, metatable: Option<Table<'lua>>) {
         let lua = self.0.lua;
         unsafe {
@@ -1177,7 +1185,7 @@ impl<'lua, T: UserData> UserDataMethods<'lua, T> {
 /// Trait for custom userdata types.
 ///
 /// By implementing this trait, a struct becomes eligible for use inside Lua code. Implementations
-/// of `ToLua` and `FromLua` are automatically provided.
+/// of [`ToLua`] and [`FromLua`] are automatically provided.
 ///
 /// # Examples
 ///
@@ -1245,6 +1253,8 @@ impl<'lua, T: UserData> UserDataMethods<'lua, T> {
 /// # }
 /// ```
 ///
+/// [`ToLua`]: trait.ToLua.html
+/// [`FromLua`]: trait.FromLua.html
 /// [`UserDataMethods`]: struct.UserDataMethods.html
 pub trait UserData: 'static + Sized {
     /// Adds custom methods and operators specific to this userdata.

src/multi.rs

@@ -5,8 +5,8 @@ use std::result::Result as StdResult;
 use error::*;
 use lua::*;
 
-/// Result is convertible to `MultiValue` following the common lua idiom of returning the result
-/// on success, or in the case of an error, returning nil followed by the error
+/// Result is convertible to `MultiValue` following the common Lua idiom of returning the result
+/// on success, or in the case of an error, returning `nil` and an error message.
 impl<'lua, T: ToLua<'lua>, E: ToLua<'lua>> ToLuaMulti<'lua> for StdResult<T, E> {
     fn to_lua_multi(self, lua: &'lua Lua) -> Result<MultiValue<'lua>> {
         let mut result = MultiValue::new();
@@ -49,14 +49,39 @@ impl<'lua> FromLuaMulti<'lua> for MultiValue<'lua> {
     }
 }
 
-/// Can be used to pass variadic values to or receive variadic values from Lua, where the type of
-/// the values is all the same and the number of values is defined at runtime.  This can be included
-/// in a tuple when converting from a MultiValue, but it must be the final entry, and it will
-/// consume the rest of the parameters given.
+/// Wraps a variable number of `T`s.
+///
+/// Can be used to work with variadic functions more easily. Using this type as the last argument of
+/// a Rust callback will accept any number of arguments from Lua and convert them to the type `T`
+/// using [`FromLua`]. `Variadic<T>` can also be returned from a callback, returning a variable
+/// number of values to Lua.
+///
+/// The [`MultiValue`] type is equivalent to `Variadic<Value>`.
+///
+/// # Examples
+///
+/// ```
+/// # extern crate rlua;
+/// # use rlua::{Lua, Variadic, Result};
+/// # fn try_main() -> Result<()> {
+/// let lua = Lua::new();
+///
+/// let add = lua.create_function(|_, vals: Variadic<f64>| -> Result<f64> {
+///     Ok(vals.iter().sum())
+/// });
+/// lua.globals().set("add", add)?;
+/// assert_eq!(lua.eval::<f64>("add(3, 2, 5)", None)?, 10.0);
+/// # Ok(())
+/// # }
+/// # fn main() {
+/// #     try_main().unwrap();
+/// # }
+/// ```
 #[derive(Debug, Clone)]
 pub struct Variadic<T>(Vec<T>);
 
 impl<T> Variadic<T> {
+    /// Creates an empty `Variadic` wrapper containing no values.
     pub fn new() -> Variadic<T> {
         Variadic(Vec::new())
     }

src/prelude.rs

@@ -1,3 +1,5 @@
+//! Re-exports most types with an extra `Lua*` prefix to prevent name clashes.
+
 pub use {Error as LuaError, Result as LuaResult, ExternalError as LuaExternalError,
          ExternalResult as LuaExternalResult, Value as LuaValue, Nil as LuaNil, ToLua, FromLua,
          MultiValue as LuaMultiValue, ToLuaMulti, FromLuaMulti, Integer as LuaInteger,