Make function module public

Reduce number of function-specific types exported to the mlua root and keep
them inside the module.

Author: khvzak

src/function.rs

@@ -1,3 +1,84 @@
+//! Lua function handling.
+//!
+//! This module provides types for working with Lua functions from Rust, including
+//! both Lua-defined functions and native Rust callbacks.
+//!
+//! # Main Types
+//!
+//! - [`Function`] - A handle to a Lua function that can be called from Rust.
+//! - [`FunctionInfo`] - Debug information about a function (name, source, line numbers, etc.).
+//! - [`CoverageInfo`] - Code coverage data for Luau functions (requires `luau` feature).
+//!
+//! # Calling Functions
+//!
+//! Use [`Function::call`] to invoke a Lua function synchronously:
+//!
+//! ```
+//! # use mlua::{Function, Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//!
+//! // Get a built-in function
+//! let print: Function = lua.globals().get("print")?;
+//! print.call::<()>("Hello from Rust!")?;
+//!
+//! // Call a function that returns values
+//! let tonumber: Function = lua.globals().get("tonumber")?;
+//! let n: i32 = tonumber.call("42")?;
+//! assert_eq!(n, 42);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! For asynchronous execution, use `Function::call_async` (requires `async` feature):
+//!
+//! ```ignore
+//! let result: String = my_async_func.call_async(args).await?;
+//! ```
+//!
+//! # Creating Functions
+//!
+//! Functions can be created from Rust closures using [`Lua::create_function`]:
+//!
+//! ```
+//! # use mlua::{Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//!
+//! let greet = lua.create_function(|_, name: String| {
+//!     Ok(format!("Hello, {}!", name))
+//! })?;
+//!
+//! lua.globals().set("greet", greet)?;
+//! let result: String = lua.load(r#"greet("World")"#).eval()?;
+//! assert_eq!(result, "Hello, World!");
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! For simpler cases, use [`Function::wrap`] or [`Function::wrap_raw`] to convert a Rust function
+//! directly:
+//!
+//! ```
+//! # use mlua::{Function, Lua, Result};
+//! # fn main() -> Result<()> {
+//! let lua = Lua::new();
+//!
+//! fn add(a: i32, b: i32) -> i32 { a + b }
+//!
+//! lua.globals().set("add", Function::wrap_raw(add))?;
+//! let sum: i32 = lua.load("add(2, 3)").eval()?;
+//! assert_eq!(sum, 5);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! # Function Environments
+//!
+//! Lua functions have an associated environment table that determines how global
+//! variables are resolved. Use [`Function::environment`] and [`Function::set_environment`]
+//! to inspect or modify this environment.
+
 use std::cell::RefCell;
 use std::os::raw::{c_int, c_void};
 use std::{mem, ptr, slice};
@@ -681,7 +762,9 @@ impl LuaType for Function {
     const TYPE_ID: c_int = ffi::LUA_TFUNCTION;
 }
 
+/// Future for asynchronous function calls.
 #[cfg(feature = "async")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct AsyncCallFuture<R: FromLuaMulti>(Result<AsyncThread<R>>);
 

src/lib.rs

@@ -76,7 +76,6 @@ mod chunk;
 mod conversion;
 mod debug;
 mod error;
-mod function;
 #[cfg(any(feature = "luau", doc))]
 mod luau;
 mod memory;
@@ -94,6 +93,7 @@ mod util;
 mod value;
 mod vector;
 
+pub mod function;
 pub mod prelude;
 
 pub use bstr::BString;
@@ -102,7 +102,7 @@ pub use ffi::{self, lua_CFunction, lua_State};
 pub use crate::chunk::{AsChunk, Chunk, ChunkMode};
 pub use crate::debug::{Debug, DebugEvent, DebugNames, DebugSource, DebugStack};
 pub use crate::error::{Error, ErrorContext, ExternalError, ExternalResult, Result};
-pub use crate::function::{Function, FunctionInfo};
+pub use crate::function::Function;
 pub use crate::multi::{MultiValue, Variadic};
 pub use crate::scope::Scope;
 pub use crate::state::{GCMode, Lua, LuaOptions, WeakLua};
@@ -130,7 +130,6 @@ pub use crate::debug::HookTriggers;
 pub use crate::{
     buffer::Buffer,
     chunk::{CompileConstant, Compiler},
-    function::CoverageInfo,
     luau::{HeapDump, NavigateError, Require, TextRequirer},
     vector::Vector,
 };

src/prelude.rs

@@ -5,16 +5,16 @@ pub use crate::{
     AnyUserData as LuaAnyUserData, BorrowedBytes as LuaBorrowedBytes, BorrowedStr as LuaBorrowedStr,
     Chunk as LuaChunk, Either as LuaEither, Error as LuaError, ErrorContext as LuaErrorContext,
     ExternalError as LuaExternalError, ExternalResult as LuaExternalResult, FromLua, FromLuaMulti,
-    Function as LuaFunction, FunctionInfo as LuaFunctionInfo, GCMode as LuaGCMode, Integer as LuaInteger,
-    IntoLua, IntoLuaMulti, LightUserData as LuaLightUserData, Lua, LuaNativeFn, LuaNativeFnMut, LuaOptions,
-    LuaString, MetaMethod as LuaMetaMethod, MultiValue as LuaMultiValue, Nil as LuaNil, Number as LuaNumber,
+    Function as LuaFunction, GCMode as LuaGCMode, Integer as LuaInteger, IntoLua, IntoLuaMulti,
+    LightUserData as LuaLightUserData, Lua, LuaNativeFn, LuaNativeFnMut, LuaOptions, LuaString,
+    MetaMethod as LuaMetaMethod, MultiValue as LuaMultiValue, Nil as LuaNil, Number as LuaNumber,
     ObjectLike as LuaObjectLike, RegistryKey as LuaRegistryKey, Result as LuaResult, StdLib as LuaStdLib,
     Table as LuaTable, TablePairs as LuaTablePairs, TableSequence as LuaTableSequence, Thread as LuaThread,
     ThreadStatus as LuaThreadStatus, UserData as LuaUserData, UserDataFields as LuaUserDataFields,
     UserDataMetatable as LuaUserDataMetatable, UserDataMethods as LuaUserDataMethods,
     UserDataRef as LuaUserDataRef, UserDataRefMut as LuaUserDataRefMut,
     UserDataRegistry as LuaUserDataRegistry, Value as LuaValue, Variadic as LuaVariadic,
-    VmState as LuaVmState, WeakLua,
+    VmState as LuaVmState, WeakLua, function::FunctionInfo as LuaFunctionInfo,
 };
 
 #[cfg(not(feature = "luau"))]
@@ -24,9 +24,8 @@ pub use crate::HookTriggers as LuaHookTriggers;
 #[cfg(feature = "luau")]
 #[doc(no_inline)]
 pub use crate::{
-    CompileConstant as LuaCompileConstant, CoverageInfo as LuaCoverageInfo,
-    NavigateError as LuaNavigateError, Require as LuaRequire, TextRequirer as LuaTextRequirer,
-    Vector as LuaVector,
+    CompileConstant as LuaCompileConstant, NavigateError as LuaNavigateError, Require as LuaRequire,
+    TextRequirer as LuaTextRequirer, Vector as LuaVector,
 };
 
 #[cfg(feature = "async")]

tests/function.rs

@@ -267,7 +267,7 @@ fn test_function_coverage() -> Result<()> {
 
     assert_eq!(
         report[0],
-        mlua::CoverageInfo {
+        mlua::function::CoverageInfo {
             function: None,
             line_defined: 1,
             depth: 0,
@@ -276,7 +276,7 @@ fn test_function_coverage() -> Result<()> {
     );
     assert_eq!(
         report[1],
-        mlua::CoverageInfo {
+        mlua::function::CoverageInfo {
             function: Some("abc".into()),
             line_defined: 4,
             depth: 1,
@@ -285,7 +285,7 @@ fn test_function_coverage() -> Result<()> {
     );
     assert_eq!(
         report[2],
-        mlua::CoverageInfo {
+        mlua::function::CoverageInfo {
             function: None,
             line_defined: 12,
             depth: 1,
@@ -294,7 +294,7 @@ fn test_function_coverage() -> Result<()> {
     );
     assert_eq!(
         report[3],
-        mlua::CoverageInfo {
+        mlua::function::CoverageInfo {
             function: None,
             line_defined: 13,
             depth: 2,