Update documentation

README.md

@@ -18,7 +18,7 @@ modules in Rust.
 
 ## Usage
 
-### Async
+### Async/await support
 
 Starting from 0.3, mlua supports async/await for all Lua versions. This works using Lua [coroutines](https://www.lua.org/manual/5.3/manual.html#2.6) and require running [Thread](https://docs.rs/mlua/latest/mlua/struct.Thread.html) along with enabling `async` feature in `Cargo.toml`.
 

src/function.rs

@@ -92,7 +92,7 @@ impl<'lua> Function<'lua> {
     /// Returns a Feature that, when polled, calls `self`, passing `args` as function arguments,
     /// and drives the execution.
     ///
-    /// Internaly it wraps the function to an AsyncThread.
+    /// Internaly it wraps the function to an [`AsyncThread`].
     ///
     /// # Examples
     ///
@@ -103,6 +103,7 @@ impl<'lua> Function<'lua> {
     /// # #[tokio::main]
     /// # async fn main() -> Result<()> {
     /// # let lua = Lua::new();
+    ///
     /// let sleep = lua.create_async_function(move |_lua, n: u64| async move {
     ///     Delay::new(Duration::from_millis(n)).await;
     ///     Ok(())
@@ -113,6 +114,8 @@ impl<'lua> Function<'lua> {
     /// # Ok(())
     /// # }
     /// ```
+    ///
+    /// [`AsyncThread`]: struct.AsyncThread.html
     #[cfg(feature = "async")]
     pub fn call_async<'fut, A, R>(&self, args: A) -> LocalBoxFuture<'fut, Result<R>>
     where

src/lib.rs

@@ -24,6 +24,12 @@
 //! 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.
 //!
+//! # Async/await support
+//!
+//! The [`create_async_function`] allows creating non-blocking functions that returns [`Future`].
+//! Lua code with async capabilities can be executed by [`call_async`] family of functions or polling
+//! [`AsyncThread`] using any runtime (eg. Tokio).
+//!
 //! [Lua programming language]: https://www.lua.org/
 //! [`Lua`]: struct.Lua.html
 //! [executing]: struct.Lua.html#method.exec
@@ -35,6 +41,10 @@
 //! [`FromLuaMulti`]: trait.FromLuaMulti.html
 //! [`UserData`]: trait.UserData.html
 //! [`UserDataMethods`]: trait.UserDataMethods.html
+//! [`create_async_function`]: struct.Lua.html#method.create_async_function
+//! [`call_async`]: struct.Function.html#method.call_async
+//! [`AsyncThread`]: struct.AsyncThread.html
+//! [`Future`]: ../futures_core/future/trait.Future.html
 
 // Deny warnings inside doc tests / examples. When this isn't present, rustdoc doesn't show *any*
 // warnings at all.

src/thread.rs

@@ -45,7 +45,10 @@ pub enum ThreadStatus {
 #[derive(Clone, Debug)]
 pub struct Thread<'lua>(pub(crate) LuaRef<'lua>);
 
-/// Thread (coroutine) representation as an async Future or Stream.
+/// Thread (coroutine) representation as an async [`Future`] or [`Stream`].
+///
+/// [`Future`]: ../futures_core/future/trait.Future.html
+/// [`Stream`]: ../futures_core/stream/trait.Stream.html
 #[cfg(feature = "async")]
 #[derive(Debug)]
 pub struct AsyncThread<'lua, R> {