From 549f96d4dcc93c60b8dae14440700ee70cd8c09c Mon Sep 17 00:00:00 2001 From: luaneko Date: Thu, 26 Jun 2025 21:32:38 +1000 Subject: [PATCH] Warn missing documentation --- crates/lb/src/chan.rs | 17 ++++++++++++++++- crates/lb/src/fs.rs | 41 +++++++++++++++++++++++++++++----------- crates/lb/src/lib.rs | 2 ++ crates/lb/src/net.rs | 17 ++++++++++++----- crates/lb/src/runtime.rs | 1 + crates/lb/src/task.rs | 17 +++++++++++++++++ 6 files changed, 78 insertions(+), 17 deletions(-) diff --git a/crates/lb/src/chan.rs b/crates/lb/src/chan.rs index 95b0875..96cbc3b 100644 --- a/crates/lb/src/chan.rs +++ b/crates/lb/src/chan.rs @@ -1,6 +1,21 @@ -// use flume::{Receiver, Sender}; +//! 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) in Lua. +/// +/// ```lua +/// local chan = require("lb:chan"); +/// ``` #[cdef(module = "lb:chan")] pub struct lb_chanlib; diff --git a/crates/lb/src/fs.rs b/crates/lb/src/fs.rs index e40aa5c..be01602 100644 --- a/crates/lb/src/fs.rs +++ b/crates/lb/src/fs.rs @@ -1,16 +1,31 @@ +//! Filesystem library +//! //! The `lb:fs` library provides synchronous and asynchronous utilities for interacting with the //! file system. //! -//! # Exports +//! ## Exports //! //! See [`lb_fslib`] for items exported by this library. use luaffi::{cdef, metatype}; -use std::io; +use thiserror::Error; use tokio::fs; +/// Errors that can be thrown by this library. +/// +/// Functions which return this error will **throw** in Lua. The error message can be caught by +/// using [`pcall(f, ...)`](https://www.lua.org/manual/5.1/manual.html#pdf-pcall). +#[derive(Debug, Error)] +pub enum Error { + /// I/O error. + #[error("{0}")] + Io(#[from] std::io::Error), +} + +type Result = std::result::Result; + /// Items exported by the `lb:fs` library. /// -/// This library can be obtained by calling `require` in Lua. +/// This library can be acquired by calling `require` in Lua. /// /// ```lua /// local fs = require("lb:fs"); @@ -25,19 +40,23 @@ impl lb_fslib { Self } - pub async extern "Lua-C" fn read(&self, path: &str) -> io::Result> { - fs::read(path).await + pub async extern "Lua-C" fn read(&self, path: &str) -> Result> { + Ok(fs::read(path).await?) } - pub extern "Lua-C" fn read_sync(&self, path: &str) -> io::Result> { - std::fs::read(path) + pub extern "Lua-C" fn read_sync(&self, path: &str) -> Result> { + Ok(std::fs::read(path)?) } - pub async extern "Lua-C" fn write(&self, path: &str, contents: &[u8]) -> io::Result<()> { - fs::write(path, contents).await + pub async extern "Lua-C" fn write(&self, path: &str, contents: &[u8]) -> Result<()> { + Ok(fs::write(path, contents).await?) } - pub extern "Lua-C" fn write_sync(&self, path: &str, contents: &[u8]) -> io::Result<()> { - std::fs::write(path, contents) + pub extern "Lua-C" fn write_sync(&self, path: &str, contents: &[u8]) -> Result<()> { + Ok(std::fs::write(path, contents)?) + } + + pub extern "Lua-C" fn readdir_sync(&self, _path: &str) -> Result<()> { + Ok(()) } } diff --git a/crates/lb/src/lib.rs b/crates/lb/src/lib.rs index fb6a5a1..42952a0 100644 --- a/crates/lb/src/lib.rs +++ b/crates/lb/src/lib.rs @@ -1,3 +1,5 @@ +//! luby standard library +#![warn(missing_docs)] pub mod runtime; #[cfg(feature = "task")] diff --git a/crates/lb/src/net.rs b/crates/lb/src/net.rs index e968324..6700a48 100644 --- a/crates/lb/src/net.rs +++ b/crates/lb/src/net.rs @@ -1,7 +1,9 @@ +//! Networking library +//! //! The `lb:net` library provides an asynchronous network API for creating TCP or UDP servers and //! clients. //! -//! # Exports +//! ## Exports //! //! See [`lb_netlib`] for items exported by this library. use derive_more::{From, FromStr}; @@ -19,10 +21,13 @@ use tokio::net::{TcpListener, TcpSocket, TcpStream}; /// using [`pcall(f, ...)`](https://www.lua.org/manual/5.1/manual.html#pdf-pcall). #[derive(Debug, Error)] pub enum Error { + /// I/O error. #[error("{0}")] Io(#[from] std::io::Error), + /// IP or socket address syntax error. #[error("{0}")] InvalidAddr(#[from] AddrParseError), + /// Socket was already converted and cannot be used. #[error("socket was already converted")] SocketConsumed, } @@ -31,7 +36,7 @@ type Result = std::result::Result; /// Items exported by the `lb:net` library. /// -/// This library can be obtained by calling +/// This library can be acquired by calling /// [`require("lb:net")`](https://www.lua.org/manual/5.1/manual.html#pdf-require) in Lua. /// /// ```lua @@ -164,7 +169,7 @@ impl lb_netlib { } } -/// An IP address, either IPv4 or IPv6. +/// IP address, either IPv4 or IPv6. /// /// # Example /// @@ -289,7 +294,7 @@ impl lb_ipaddr { } } -/// A socket address, which is an IP address with a port number. +/// Socket address, which is an IP address with a port number. #[derive(Debug, Clone, Copy, PartialEq, Eq, From, FromStr)] #[cdef] pub struct lb_socketaddr(#[opaque] SocketAddr); @@ -345,7 +350,7 @@ impl lb_socketaddr { } } -/// A TCP socket which has not yet been converted to an [`lb_tcpstream`] or [`lb_tcplistener`]. +/// TCP socket which has not yet been converted to an [`lb_tcpstream`] or [`lb_tcplistener`]. #[derive(Debug, From)] #[cdef] pub struct lb_tcpsocket(#[opaque] Option); @@ -465,6 +470,7 @@ impl lb_tcpsocket { } } +/// TCP connection between a local and a remote socket. #[derive(Debug, From)] #[cdef] pub struct lb_tcpstream(#[opaque] TcpStream); @@ -472,6 +478,7 @@ pub struct lb_tcpstream(#[opaque] TcpStream); #[metatype] impl lb_tcpstream {} +/// TCP socket server, listening for connections. #[derive(Debug, From)] #[cdef] pub struct lb_tcplistener(#[opaque] TcpListener); diff --git a/crates/lb/src/runtime.rs b/crates/lb/src/runtime.rs index 0d1c857..39bd6e1 100644 --- a/crates/lb/src/runtime.rs +++ b/crates/lb/src/runtime.rs @@ -1,3 +1,4 @@ +#![doc(hidden)] use derive_more::{Deref, DerefMut}; use luaffi::{Module, Registry}; use luajit::{Chunk, State}; diff --git a/crates/lb/src/task.rs b/crates/lb/src/task.rs index 02b20f3..518d84b 100644 --- a/crates/lb/src/task.rs +++ b/crates/lb/src/task.rs @@ -1,9 +1,25 @@ +//! Task library +//! +//! The `lb:task` library primitives for asynchronous communication between tasks via message +//! passing channels. +//! +//! ## Exports +//! +//! See [`lb_tasklib`] for items exported by this library. use crate::runtime::spawn; use luaffi::{cdef, metatype}; use luajit::{LUA_MULTRET, Type}; use std::{ffi::c_int, time::Duration}; use tokio::{task::JoinHandle, time::sleep}; +/// Items exported by the `lb:task` library. +/// +/// This library can be acquired by calling +/// [`require("lb:task")`](https://www.lua.org/manual/5.1/manual.html#pdf-require) in Lua. +/// +/// ```lua +/// local task = require("lb:task"); +/// ``` #[cdef(module = "lb:task")] pub struct lb_tasklib; @@ -56,6 +72,7 @@ impl lb_tasklib { } } +/// Handle for an asynchronous task created by [`spawn`](lb_tasklib::spawn). #[cdef] pub struct lb_task { #[opaque]