Update docs

crates/luaify/src/lib.rs

@@ -1,6 +1,53 @@
 //! # luaify
 //!
-//! A Rust for generating Lua code from Rust syntax.
+//! A macro for generating Lua code from Rust syntax.
+//!
+//! This macro performs a direct one-to-one translation of Rust expressions and blocks into
+//! equivalent Lua code. For example,
+//!
+//! ```rust
+//! use luaify::luaify;
+//!
+//! luaify!(|a, b| {
+//!     let c = a + b;
+//!
+//!     fn inner_function(c: _) {
+//!         print(concat!("the sum of ", a, " and ", b, " is ", c));
+//!         c
+//!     }
+//!
+//!     inner_function(c);
+//! });
+//! ```
+//!
+//! will translate to the following equivalent Lua code (embedded as an [`&str`] or [`String`] in
+//! Rust):
+//!
+//! ```lua
+//! function(a, b)
+//!     local c = a + b
+//!
+//!     local function inner_function(c)
+//!         print("the sum of " .. a .. " and " .. b .. " is " .. c)
+//!         return c
+//!     end
+//!
+//!     inner_function(c)
+//! end
+//! ```
+//!
+//! This macro accepts a smaller subset of all valid Rust syntax due to the difference between
+//! Rust's expression-based syntax and Lua's statement-based syntax. Most Rust syntax are translated
+//! to their equivalents in Lua, however the following features are not supported and will result in
+//! a compile-time error:
+//!
+//! - static typing (typed local variables, parameters and return types in function signatures,
+//!   etc.)
+//! - pattern matching (e.g. `match`, `if let`, `while let`)
+//! - items other than statements or functions (e.g. `struct`, `enum`, `trait`, `impl`)
+//! - block statements in expression position (e.g. `if`, `while`, `for`, `loop` that evaluate to a
+//!   value)
+//! - expressions in statement position (except for function calls and assignments)
 use crate::{
     generate::{generate, generate_chunk},
     transform::{transform, transform_chunk},
@@ -13,6 +60,7 @@ mod generate;
 mod transform;
 mod utils;
 
+/// Generates Lua code for the given expression.
 #[proc_macro]
 pub fn luaify(input: TokenStream1) -> TokenStream1 {
     let mut expr = parse_macro_input!(input);
@@ -23,6 +71,7 @@ pub fn luaify(input: TokenStream1) -> TokenStream1 {
     .into()
 }
 
+/// Generates Lua code for the given block.
 #[proc_macro]
 pub fn luaify_chunk(input: TokenStream1) -> TokenStream1 {
     let mut block = parse_macro_input!(input);