Add documentation, remove dependency on rlua default features.

AlphaModder · AlphaModder · commit 576840ed9cd4 · 2019-06-08T04:31:29.000-07:00
diff --git a/include-lua/Cargo.toml b/include-lua/Cargo.toml
@@ -3,12 +3,12 @@ name = "include-lua"
 description = "A crate that allows the embedding of a lua source tree into a Rust application binary."
 repository = "https://github.com/AlphaModder/include-lua"
 readme = "../README.md"
-version = "0.1.3"
+version = "0.1.4"
 license = "MIT"
 authors = ["AlphaModder"]
 edition = "2018"
 
 [dependencies]
-rlua = "0.16.2"
+rlua = { version = "0.16", default-features = false }
 include-lua-macro = "0.1.2"
 proc-macro-hack = "0.5.4"
diff --git a/include-lua/src/lib.rs b/include-lua/src/lib.rs
@@ -3,9 +3,14 @@ use std::collections::HashMap;
 use proc_macro_hack::proc_macro_hack;
 use rlua::{Result, Context, UserData, UserDataMethods, MetaMethod, Value, Table, RegistryKey};
 
+/// A macro that embeds a lua source tree on disk into the binary, similarly to how `include_str!`
+/// can include a single file. Called like `include_lua!("name": "path")`, where name is a label
+/// that appears in lua stacktraces involving code loaded from the tree, and path specifies a folder
+/// relative to `src/` in which the tree can be found. `name` defaults to `path` if omitted.
 #[proc_macro_hack]
 pub use include_lua_macro::include_lua;
 
+/// Represents a Lua source tree embedded into a binary via [`include_lua!`][include_lua].
 pub struct LuaModules {
     files: HashMap<String, (String, String)>,
     prefix: String,
@@ -18,6 +23,9 @@ impl LuaModules {
     }
 }
 
+/// A piece of [`UserData`][UserData] that acts like a Lua searcher.
+/// When called as a function with a single string parameter, attempts to load
+/// (but not execute) a module by that name. If no module is found, returns nil.
 pub struct Searcher(LuaModules, RegistryKey);
 
 impl UserData for Searcher {
@@ -37,10 +45,20 @@ impl UserData for Searcher {
     }
 }
 
+/// An extension trait for [`Context`][Context] that allows the loading of [`LuaModules`][LuaModules] instances.
 pub trait ContextExt<'a> {
+    /// Makes the source tree represented by `modules` accessible to `require` calls within this context.
     fn add_modules(&self, modules: LuaModules) -> Result<()>;
+
+    /// Makes the source tree represented by `modules` accessible to `require` calls within this context.
+    /// All modules loaded from the source tree will have their environment set to `environment`.
     fn add_modules_with_env(&self, modules: LuaModules, environment: Table<'a>) -> Result<()>;
+
+    /// Creates a [`Searcher`][Searcher] instance from the given [`LuaModules`][LuaModules] instance.
     fn make_searcher(&self, modules: LuaModules) -> Result<Searcher>;
+
+    /// Creates a [`Searcher`][Searcher] instance from the given [`LuaModules`][LuaModules] instance.
+    /// All modules loaded by the searcher will have their environment set to `environment`.
     fn make_searcher_with_env(&self, modules: LuaModules, environment: Table<'a>) -> Result<Searcher>;
 }
 
