Update docs

crates/lb/src/chan.rs

@@ -1,79 +0,0 @@
-//! # Channel library
-//!
-//! The `lb:chan` library provides primitives for asynchronous communication between tasks via
-//! message passing channels.
-//!
-//! ## Exports
-//!
-//! See [`lb_chanlib`] for items exported by this library.
-use luaffi::{cdef, metatype};
-
-/// Items exported by the `lb:chan` library.
-///
-/// This library can be acquired by calling
-/// [`require("lb:chan")`](https://www.lua.org/manual/5.1/manual.html#pdf-require).
-///
-/// ```lua
-/// local chan = require("lb:chan");
-/// ```
-#[cdef(module = "lb:chan")]
-pub struct lb_chanlib;
-
-#[metatype]
-impl lb_chanlib {
-    #[new]
-    extern "Lua-C" fn new() -> Self {
-        Self
-    }
-
-    extern "Lua" fn unbounded(self) {
-        let (send, recv) = (__new(__ct.lb_sender), __new(__ct.lb_receiver));
-        self.__unbounded(send, recv);
-        (send, recv)
-    }
-
-    extern "Lua" fn bounded(self, cap: u32) {
-        assert(cap >= 0, "channel capacity must be nonnegative");
-        let (send, recv) = (__new(__ct.lb_sender), __new(__ct.lb_receiver));
-        self.__bounded(cap, send, recv);
-        (send, recv)
-    }
-
-    // extern "Lua-C" fn __unbounded(&self, s: *mut lb_sender, r: *mut lb_receiver) {
-    //     let (send, recv) = flume::unbounded();
-    //     unsafe {
-    //         ptr::write(s, lb_sender { send });
-    //         ptr::write(r, lb_receiver { recv });
-    //     }
-    // }
-
-    // extern "Lua-C" fn __bounded(&self, cap: usize, s: *mut lb_sender, r: *mut lb_receiver) {
-    //     let (send, recv) = flume::bounded(cap);
-    //     unsafe {
-    //         ptr::write(s, lb_sender { send });
-    //         ptr::write(r, lb_receiver { recv });
-    //     }
-    // }
-}
-
-// #[cdef]
-// pub struct lb_sender {
-//     #[opaque]
-//     send: Sender<c_int>,
-// }
-
-// #[metatype]
-// impl lb_sender {
-//     extern "Lua" fn send(self, value: _) {
-//         let key = __ref(value);
-//     }
-// }
-
-// #[cdef]
-// pub struct lb_receiver {
-//     #[opaque]
-//     recv: Receiver<c_int>,
-// }
-
-// #[metatype]
-// impl lb_receiver {}

crates/lb/src/fs.rs

@@ -1,4 +1,4 @@
-//! # Filesystem library
+//! Filesystem library.
 //!
 //! The `lb:fs` library provides synchronous and asynchronous utilities for interacting with the
 //! filesystem.

crates/lb/src/lib.rs

@@ -1,6 +1,4 @@
-//! luby standard library
+//! luby core libraries.
-#[cfg(feature = "task")]
-pub mod chan;
 #[cfg(feature = "fs")]
 pub mod fs;
 #[cfg(feature = "net")]

crates/lb/src/net.rs

@@ -1,7 +1,7 @@
-//! # Networking library
+//! Network library.
 //!
-//! The `lb:net` library provides an asynchronous network API for creating TCP or UDP servers and
+//! The `lb:net` library provides an asynchronous network API for woring with TCP, UDP and IPC
-//! clients.
+//! sockets.
 //!
 //! ## Exports
 //!

crates/lb/src/task.rs

@@ -1,7 +1,7 @@
-//! # Task library
+//! Task library.
 //!
-//! The `lb:task` library primitives for asynchronous communication between tasks via message
+//! The `lb:task` library provides utilities for the scheduling of and communication between
-//! passing channels.
+//! asynchronous tasks.
 //!
 //! ## Exports
 //!

crates/lb/src/time.rs

@@ -1,5 +1,21 @@
+//! Time library.
+//!
+//! The `lb:time` library provides utilities for working with the date and time and its related
+//! constructs.
+//!
+//! ## Exports
+//!
+//! See [`lb_timelib`] for items exported by this library.
 use luaffi::{cdef, metatype};
 
+/// Items exported by the `lb:time` library.
+///
+/// This library can be acquired by calling
+/// [`require("lb:time")`](https://www.lua.org/manual/5.1/manual.html#pdf-require).
+///
+/// ```lua
+/// local time = require("lb:time");
+/// ```
 #[cdef(module = "lb:time")]
 pub struct lb_timelib;
 
@@ -10,11 +26,13 @@ impl lb_timelib {
         Self
     }
 
+    /// Returns an instant object that represents the current time at the time of calling.
     pub extern "Lua-C" fn instant() -> lb_instant {
         lb_instant::new(std::time::Instant::now())
     }
 }
 
+/// Represents the measurement of a monotonically nondecreasing clock.
 #[cdef]
 pub struct lb_instant(#[opaque] std::time::Instant);
 
@@ -24,7 +42,8 @@ impl lb_instant {
         Self(instant)
     }
 
-    pub extern "Lua-C" fn elapsed(&self) -> f64 {
+    /// Returns the number of seconds elapsed since this instant was measured.
+    pub extern "Lua-C" fn elapsed_secs(&self) -> f64 {
         self.0.elapsed().as_secs_f64()
     }
 }

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);

crates/luajit-sys/lib.rs

@@ -1,3 +1,18 @@
+//! Raw bindings for LuaJIT generated using [bindgen](https://docs.rs/bindgen/).
+//!
+//! ## Feature flags
+//!
+//! Features flags are used to control certain features of LuaJIT. They are not enabled by default
+//! unless otherwise specified below.
+//!
+//! - `runtime`: links the target with `libluajit`. This should only be enabled by binary targets.
+//! - `jit`: enables the JIT compiler. *This is enabled by default.*
+//! - `ffi`: enables the FFI library. *This is enabled by default.*
+//! - `unwind`: configures LuaJIT to use stack unwinding instead of `longjmp` for error handling.
+//!   **This MUST be enabled if `panic = "unwind"` is set.**
+//! - `bundled-alloc`: configures LuaJIT to include its own bundled allocator. If this is not
+//!   enabled, LuaJIT will use the system allocator by default.
+//! - `lua52`: enables Lua 5.2 compatibility mode. *This is enabled by default.*
 #![allow(nonstandard_style)]
 use std::{ffi::*, ptr};
 

crates/luajit/src/lib.rs

@@ -1,3 +1,4 @@
+//! Safe LuaJIT bindings for Rust.
 #![allow(non_snake_case)]
 use bitflags::bitflags;
 use bstr::{BStr, BString, ByteSlice};

src/lib.rs

@@ -1,5 +1,4 @@
-#[cfg(feature = "task")]
+//! luby standard library.
-pub use lb::chan;
 #[cfg(feature = "fs")]
 pub use lb::fs;
 #[cfg(feature = "net")]
@@ -13,8 +12,6 @@ pub use lb::time;
 pub fn open(#[allow(unused)] rt: &mut lb::runtime::Builder) {
     #[cfg(feature = "task")]
     rt.module::<task::lb_tasklib>();
-    #[cfg(feature = "task")]
-    rt.module::<chan::lb_chanlib>();
     #[cfg(feature = "time")]
     rt.module::<time::lb_timelib>();
     #[cfg(feature = "fs")]

tests/main.lua

@@ -117,7 +117,7 @@ local function main(item)
       fail = fail + 1
     end
   end
-  local elapsed = time:elapsed()
+  local elapsed = time:elapsed_secs()
   local code = 1
   if fail == 0 then
     print("", style("pass", ("%s %d tests passed"):format(icon.check, pass)))