Add more documentation to luajit crate

crates/luajit/src/lib.rs

@@ -19,6 +19,11 @@ use std::{
 };
 use thiserror::Error;
 
+/// LuaJIT version string.
+pub fn version() -> &'static str {
+    LUAJIT_VERSION.to_str().unwrap()
+}
+
 /// Lua error.
 #[derive(Debug, Error)]
 #[non_exhaustive]
@@ -149,7 +154,7 @@ pub enum Status {
     /// Thread is alive (currently running or can run a function).
     #[default]
     Normal,
-    /// Thread terminated with an error and cannot be resumed.
+    /// Thread terminated with an error and can no longer be used.
     Dead,
     /// Thread suspended with `coroutine.yield(...)` and is awaiting resume.
     Suspended,
@@ -166,7 +171,7 @@ impl Status {
         })
     }
 
-    /// Name of this status, like `"normal"` or `"dead"`.
+    /// Name of this status, like `"normal"` or `"suspended"`.
     pub fn name(&self) -> &'static str {
         match self {
             Status::Normal => "normal",
@@ -430,8 +435,7 @@ impl Drop for GlobalState {
 
 /// Lua value handle into the registry.
 ///
-/// The value is managed by [`luaL_ref`] and [`luaL_unref`] with [`LUA_REGISTRYINDEX`] as the target
-/// table.
+/// Equivalent to [`luaL_ref`] and [`luaL_unref`] with [`LUA_REGISTRYINDEX`] as the target table.
 #[derive(Debug)]
 pub struct Ref {
     state: Rc<GlobalState>,
@@ -1306,7 +1310,12 @@ impl<'s> Slot<'s> {
     }
 }
 
+/// Pushes a value onto a [`Stack`].
+///
+/// This trait can be implemented by any type that can be reasonably converted to an equivalent Lua
+/// value. Any type implementing this trait can be passed as an argument to [`Stack::push`].
 pub trait Push {
+    /// Pushes this value to the given stack.
     fn push(&self, stack: &mut Stack);
 }
 
@@ -1413,8 +1422,14 @@ impl_push_str!(BString);
 impl_push_str!(&str);
 impl_push_str!(String);
 
+/// [`Push`]es a copy of the value at an index onto a [`Stack`].
+///
+/// Equivalent to [`lua_pushvalue`].
 #[derive(Debug, Default, Clone, Copy, Hash)]
-pub struct Index(pub c_int);
+pub struct Index(
+    /// Index of the value to copy.
+    pub c_int,
+);
 
 impl Push for Index {
     fn push(&self, stack: &mut Stack) {
@@ -1423,25 +1438,38 @@ impl Push for Index {
     }
 }
 
+/// [`Push`]es a new table onto a [`Stack`].
+///
+/// This value can be used as an argument to [`Stack::push`] to create a new empty table onto the
+/// stack.
+///
+/// Equivalent to [`lua_createtable`].
 #[derive(Debug, Default, Clone, Copy, Hash)]
 pub struct NewTable {
+    /// Size of the preallocated array part.
     pub narr: c_int,
+    /// Size of the preallocated hash part.
     pub nrec: c_int,
 }
 
 impl NewTable {
+    /// Creates a new [`NewTable`] with no preallocations defined.
     pub fn new() -> Self {
         Self::new_sized(0, 0)
     }
 
+    /// Creates a new [`NewTable`] with the array part set to preallocate `size`.
     pub fn new_array(size: c_int) -> Self {
         Self::new_sized(size, 0)
     }
 
+    /// Creates a new [`NewTable`] with the hash part set to preallocate `size`.
     pub fn new_record(size: c_int) -> Self {
         Self::new_sized(0, size)
     }
 
+    /// Creates a new [`NewTable`] with the array and hash parts set to preallocate `narr` and
+    /// `rec`.
     pub fn new_sized(narr: c_int, nrec: c_int) -> Self {
         Self { narr, nrec }
     }
@@ -1457,6 +1485,12 @@ impl Push for NewTable {
     }
 }
 
+/// [`Push`]es the current thread onto a [`Stack`].
+///
+/// This value can be used as an argument to [`Stack::push`] to push the current thread as a
+/// `coroutine` object onto the stack.
+///
+/// Equivalent to [`lua_pushthread`].
 #[derive(Debug, Default, Clone, Copy, Hash)]
 pub struct CurrentThread;
 
@@ -1467,7 +1501,13 @@ impl Push for CurrentThread {
     }
 }
 
+/// Parses a value on a [`Stack`].
+///
+/// This trait can be implemented by any type that can be reasonably converted from an equivalent
+/// Lua value. Any type implementing this trait can be passed as a generic argument to
+/// [`Slot::parse`].
 pub trait Parse<'s>: Sized {
+    /// Parses the value in the given slot.
     fn parse(slot: &Slot<'s>) -> Result<Self, Error>;
 }