From 4e961dac405283c9a0dc688b9bcf6c3d1e54390b Mon Sep 17 00:00:00 2001 From: Olivia Brooks <109807080+Cutieguwu@users.noreply.github.com> Date: Sun, 22 Feb 2026 13:46:03 -0500 Subject: [PATCH] Add documentation. --- crates/core/src/workspace.rs | 91 +++++++++++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 2 deletions(-) diff --git a/crates/core/src/workspace.rs b/crates/core/src/workspace.rs index c435729..8ad18d6 100644 --- a/crates/core/src/workspace.rs +++ b/crates/core/src/workspace.rs @@ -14,6 +14,10 @@ use crate::package::PackageHandler; use crate::prey::{F_PREY_LOCK, F_PREY_TOML, Prey}; use crate::{Error, package}; +/// Represents a raven workspace. +/// +/// [`WorkspaceHandler`] manages project compilation, cache writing, +/// and tracking of all packages that make up the workspace. #[derive(Debug)] pub struct WorkspaceHandler { nest: Nest, @@ -26,6 +30,13 @@ impl WorkspaceHandler { const DIR_SRC: &str = "src/"; const DIR_TARGET: &str = "target/"; + /// Creates a new [`WorkspaceHandler`] instance at the provided path. + /// + /// # Errors + /// + /// * [`Error::Io`] if the `project_root` cannot be canonicalized. + /// * [`Error::MissingFileName`] if a name for the workspace cannot be derived + /// from the `project_root` pub fn new>(project_root: P) -> crate::Result { let project_root = project_root.as_ref().canonicalize()?; @@ -42,6 +53,14 @@ impl WorkspaceHandler { }) } + /// Loads an existing workspace from the provided path. + /// + /// # Errors + /// + /// * [`Error::Io`] for any number of IO-related errors. + /// Unwrap the [`std::io::Error`] for further information. + /// * [`Error::MissingFileName`] if a name for the workspace cannot be derived + /// from the `project_root` pub fn load>(project_root: P) -> crate::Result { let project_root = project_root.as_ref().canonicalize()?; @@ -57,6 +76,7 @@ impl WorkspaceHandler { Ok(workspace_manager) } + /// Writes all lock files (Nest.toml, src/**/Prey.toml) to the disk. pub fn write_locks(&self) -> crate::Result<()> { if let Option::Some(lock) = self.nest_lock.clone() { lock.write(self.project_root.join(F_NEST_LOCK))?; @@ -69,6 +89,26 @@ impl WorkspaceHandler { Ok(()) } + /// Initializes a new workspace. + /// + /// # Behaviour + /// + /// Init will avoid overwriting or adding an example project if raven is being integrated into + /// an existing workspace codebase. + /// + /// Init will always write: + /// + /// * Nest.toml + /// * .java-version + /// * Attempt to append to .gitignore + /// + /// If this is an empty workspace, init will include: + /// + /// * Calling `git init` + /// * Writing an example project. + /// * Automatic package discovery. + /// + /// # Errors pub fn init(&mut self) -> crate::Result<&mut Self> { // ORDER MATTERS. let is_empty = read_dir(self.project_root.as_path()).is_ok_and(|tree| tree.count() == 0); @@ -114,7 +154,18 @@ impl WorkspaceHandler { Ok(self) } - // This is the naive build + /// This is a naive build; it attempts to build every source file individually. + /// + /// It calls [`PackageHandler::get_outdated()`] on all known packages to determine + /// compile targets. + /// + /// It will then attempt to write all locks to update the caches and avoid attempting to + /// needlessly recompile targets. + /// + /// # Errors + /// + /// * [`Error::AbsentPrimeError`] + /// * [`Error::Io`] pub fn build(&mut self) -> crate::Result<&mut Self> { let compiler = java::compiler::CompilerBuilder::new() .class_path(Self::DIR_TARGET) @@ -152,6 +203,20 @@ impl WorkspaceHandler { Ok(self) } + /// Attempts to call the JVM to run, in order of precedence: + /// + /// 1. Provided entry point which includes a specific source file. + /// 2. Provided entry point to a package, using that package's default entry point + /// defined in it's `Prey.toml` + /// 3. The workspace's default package defined in `Nest.toml`, and that package's default + /// entry point as defined in it's `Prey.toml`. + /// + /// # Errors + /// + /// * [`Error::UnknownPackage`] if the package cannot be found. + /// * [`Error::UndefinedEntryPoint`] if no fallback entry point can be found. + /// * [`Error::Io`] + /// * [`Error::Java`] pub fn run>( &mut self, entry_point: Option

, @@ -187,6 +252,11 @@ impl WorkspaceHandler { Ok(self) } + /// Cleans the workspace of it's caches: + /// + /// * `target/` + /// * Nest.lock + /// * Prey.lock pub fn clean(&mut self) -> crate::Result<&mut Self> { // Clear Nest.lock if let Err(err) = std::fs::remove_file(self.project_root.join(F_NEST_LOCK)) { @@ -215,7 +285,14 @@ impl WorkspaceHandler { Ok(self) } - /// Add any newly created packages. + /// Scan for newly created packages, wrapping them in [`PackageHandler`]s + /// and adding them to the [`WorkspaceHandler`]'s package map. + /// + /// Packages are identified by their `Prey.toml` manifests. + /// + /// # Errors + /// + /// * [`Error::Io`] fn discover_packages(&mut self) -> crate::Result<()> { // Scan the src/ directory for entries, // filter out the files, @@ -280,10 +357,18 @@ impl WorkspaceHandler { Ok(()) } + /// Writes the [`WorkspaceHandler`]'s `Nest.toml` to disk. fn write_nest(&self) -> crate::Result<()> { Ok(self.nest.write(self.project_root.clone())?) } + /// Writes a `.java-version` file for `jenv` to the disk with an automatically parsed + /// java version from [`java::get_javac_version()`]. + /// + /// # Errors + /// + /// * [`Error::Io`] + /// * [`Error::Java`] fn write_java_version(&self) -> crate::Result<()> { if let Result::Ok(mut f) = OpenOptions::new() .write(true) @@ -296,6 +381,7 @@ impl WorkspaceHandler { Ok(()) } + /// Writes an example project tree to disk. fn write_dir_tree(&self) -> std::io::Result<()> { for dir in [ format!("{}main/java", Self::DIR_SRC), @@ -308,6 +394,7 @@ impl WorkspaceHandler { Ok(()) } + /// Writes an example project to disk. fn write_example_project(&self) -> crate::Result<()> { let main: PathBuf = PathBuf::from(Self::DIR_SRC).join("main/"); let test: PathBuf = PathBuf::from(Self::DIR_SRC).join("test/");