Add doc comments

Author: khvzak

.github/workflows/main.yml

@@ -121,7 +121,7 @@ jobs:
     - uses: dtolnay/rust-toolchain@stable
       with:
         target: ${{ matrix.target }}
-    - name: Run tests
+    - name: Run standalone tests
       run: |
         cargo test
 

src/lib.rs

@@ -2,6 +2,7 @@ use std::env;
 use std::fs;
 use std::path::{Path, PathBuf};
 
+/// Represents the version of Lua to build.
 #[derive(Debug, PartialEq, Eq)]
 pub enum Version {
     Lua51,
@@ -11,6 +12,7 @@ pub enum Version {
 }
 pub use self::Version::*;
 
+/// Represents the configuration for building Lua artifacts.
 pub struct Build {
     out_dir: Option<PathBuf>,
     target: Option<String>,
@@ -19,6 +21,7 @@ pub struct Build {
     debug: Option<bool>,
 }
 
+/// Represents the artifacts produced by the build process.
 #[derive(Clone, Debug)]
 pub struct Artifacts {
     include_dir: PathBuf,
@@ -39,35 +42,55 @@ impl Default for Build {
 }
 
 impl Build {
+    /// Creates a new `Build` instance with default settings.
     pub fn new() -> Build {
         Build::default()
     }
 
+    /// Sets the output directory for the build artifacts.
+    ///
+    /// This is required if called outside of a build script.
     pub fn out_dir<P: AsRef<Path>>(&mut self, path: P) -> &mut Build {
         self.out_dir = Some(path.as_ref().to_path_buf());
         self
     }
 
+    /// Sets the target architecture for the build.
+    ///
+    /// This is required if called outside of a build script.
     pub fn target(&mut self, target: &str) -> &mut Build {
         self.target = Some(target.to_string());
         self
     }
 
+    /// Sets the host architecture for the build.
+    ///
+    /// This is optional and will default to the environment variable `HOST` if not set.
+    /// If called outside of a build script, it will default to the target architecture.
     pub fn host(&mut self, host: &str) -> &mut Build {
         self.host = Some(host.to_string());
         self
     }
 
+    /// Sets the optimization level for the build.
+    ///
+    /// This is optional and will default to the environment variable `OPT_LEVEL` if not set.
+    /// If called outside of a build script, it will default to `0` in debug mode and `2` otherwise.
     pub fn opt_level(&mut self, opt_level: &str) -> &mut Build {
         self.opt_level = Some(opt_level.to_string());
         self
     }
 
+    /// Sets whether to build in debug mode.
+    ///
+    /// This is optional and will default to the value of `cfg!(debug_assertions)`.
+    /// If set to `true`, it also enables Lua API checks.
     pub fn debug(&mut self, debug: bool) -> &mut Build {
         self.debug = Some(debug);
         self
     }
 
+    /// Builds the Lua artifacts for the specified version.
     pub fn build(&self, version: Version) -> Artifacts {
         let target = &self.target.as_ref().expect("TARGET is not set")[..];
         let out_dir = self.out_dir.as_ref().expect("OUT_DIR is not set");
@@ -213,18 +236,25 @@ impl Version {
 }
 
 impl Artifacts {
+    /// Returns the directory containing the Lua headers.
     pub fn include_dir(&self) -> &Path {
         &self.include_dir
     }
 
+    /// Returns the directory containing the Lua libraries.
     pub fn lib_dir(&self) -> &Path {
         &self.lib_dir
     }
 
+    /// Returns the names of the Lua libraries built.
     pub fn libs(&self) -> &[String] {
         &self.libs
     }
 
+    /// Prints the necessary Cargo metadata for linking the Lua libraries.
+    ///
+    /// This method is typically called in a build script to inform Cargo
+    /// about the location of the Lua libraries and how to link them.
     pub fn print_cargo_metadata(&self) {
         println!("cargo:rustc-link-search=native={}", self.lib_dir.display());
         for lib in self.libs.iter() {