Warn missing documentation

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;
 

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<T> = std::result::Result<T, Error>;
+
 /// 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<Vec<u8>> {
-        fs::read(path).await
+    pub async extern "Lua-C" fn read(&self, path: &str) -> Result<Vec<u8>> {
+        Ok(fs::read(path).await?)
     }
 
-    pub extern "Lua-C" fn read_sync(&self, path: &str) -> io::Result<Vec<u8>> {
-        std::fs::read(path)
+    pub extern "Lua-C" fn read_sync(&self, path: &str) -> Result<Vec<u8>> {
+        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(())
     }
 }

crates/lb/src/lib.rs

@@ -1,3 +1,5 @@
+//! luby standard library
+#![warn(missing_docs)]
 pub mod runtime;
 
 #[cfg(feature = "task")]

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<T> = std::result::Result<T, Error>;
 
 /// 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<TcpSocket>);
@@ -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);

crates/lb/src/runtime.rs

@@ -1,3 +1,4 @@
+#![doc(hidden)]
 use derive_more::{Deref, DerefMut};
 use luaffi::{Module, Registry};
 use luajit::{Chunk, State};

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]