From d3423bdf29cc75b3bd3aa5fd4d54509152046a5f Mon Sep 17 00:00:00 2001 From: Shautvast Date: Tue, 16 Jan 2024 11:14:38 +0100 Subject: [PATCH] added rustdocs for most functions/structs --- src/compile/mod.rs | 4 ++++ src/config.rs | 2 ++ src/deploader.rs | 13 ++++++++++++- src/lib.rs | 8 ++++++++ src/main.rs | 1 + src/pom/model.rs | 1 + 6 files changed, 28 insertions(+), 1 deletion(-) diff --git a/src/compile/mod.rs b/src/compile/mod.rs index 9a8a08f..258d83f 100644 --- a/src/compile/mod.rs +++ b/src/compile/mod.rs @@ -17,12 +17,14 @@ const TARGET_MAIN: &str = "target/classes"; const TARGET_TEST: &str = "target/test-classes"; +/// internal view of the src filesystem #[derive(Debug)] enum PathNode { DirNode(PathBuf, Vec, Vec), FileNode(PathBuf), } +/// runs the compile stage pub fn run(project: &Project) -> Result<(), Error> { println!("{} {}.{}-{}", "Compiling".green(), project.group, project.name, project.version); @@ -37,6 +39,7 @@ pub fn run(project: &Project) -> Result<(), Error> { Ok(()) } +/// walks the source tree and compiles any java files fn compile_sourcedir(project: &Project, src_tree: &mut PathNode) -> Result<(), Error> { if let DirNode(dir_name, subdirs, contents) = src_tree { if !contents.is_empty() { @@ -81,6 +84,7 @@ fn compile_sourcedir(project: &Project, src_tree: &mut PathNode) -> Result<(), E Ok(()) } +/// the source tree on disk is first read into memory fn determine_src_tree(parent: PathBuf, parent_node: &mut PathNode) -> Result<(), Error> { let paths = fs::read_dir(&parent)?; diff --git a/src/config.rs b/src/config.rs index 474fba2..92041c4 100644 --- a/src/config.rs +++ b/src/config.rs @@ -1,6 +1,7 @@ use std::path::PathBuf; use std::sync::OnceLock; +/// Contains any config elements pub struct Config { pub cache_location: String, pub maven_central: String, @@ -9,6 +10,7 @@ pub struct Config { pub static CONFIG: OnceLock = OnceLock::new(); +/// default config pub fn config() -> &'static Config { CONFIG.get_or_init(|| { let user_home = home::home_dir().unwrap(); diff --git a/src/deploader.rs b/src/deploader.rs index c5a620d..59a93bb 100644 --- a/src/deploader.rs +++ b/src/deploader.rs @@ -14,6 +14,17 @@ use crate::config::config; use crate::pom::model::Pom; use colored::Colorize; +/// Loads a list of artifacts from remote repo or local cache +/// +/// 1. check if calculated location (directory) exists on local disk +/// 2. if not create it +/// 3. checks if jar exists on local disk +/// 4. if not downloads it from a repo (now mavencentral only) +/// 5. downloads/reads from disk the SHA1 (hex) file and compares it with the calculated one for the jar (this is done always) +/// 6. checks if pom exists on local disk +/// 7. if not downloads it from a repo (now mavencentral only) +/// 8. verifies the SHA1 as for the jar +/// 9. extracts the transitive dependencies from the pom and recurses to (1) for the list of dependencies pub fn load_artifacts(artifacts: &[Artifact]) -> Result<(), Error> { for art in artifacts { load_artifact(art)?; @@ -21,7 +32,7 @@ pub fn load_artifacts(artifacts: &[Artifact]) -> Result<(), Error> { Ok(()) } -pub fn load_artifact(art: &Artifact) -> Result<(), Error> { +fn load_artifact(art: &Artifact) -> Result<(), Error> { let artifact_path = format!("{}/{}/{}", art.group.replace(".", "/"), art.name, art.version); // check/create artifact directory diff --git a/src/lib.rs b/src/lib.rs index f32a71b..8574cd3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,6 +9,7 @@ mod config; pub mod deploader; pub mod compile; +/// Top struct for jargo project data #[derive(Debug)] pub struct Project { pub group: String, @@ -19,6 +20,7 @@ pub struct Project { pub project_root: String, } +/// The identifier for any released bundle (jar, war etc) like in maven #[derive(Debug)] pub struct Artifact { pub group: String, @@ -26,6 +28,7 @@ pub struct Artifact { pub version: String, } +/// Convert from XML view impl From for Artifact { fn from(value: pom::model::Dependency) -> Self { Artifact { @@ -37,6 +40,8 @@ impl From for Artifact { } impl Artifact { + + /// Convert from TOML view pub fn from_table_entry(name_group: &str, version: String) -> Result{ let name_group_split: Vec<&str> = name_group.split(":").collect(); if 2 != name_group_split.len(){ @@ -53,6 +58,7 @@ impl Artifact { } } +/// loads the project from the TOML file pub fn load_project(jargo_file: Option<&str>) -> Result { let jargo = Path::new(jargo_file.unwrap_or("./Jargo.toml")); @@ -74,6 +80,7 @@ pub fn load_project(jargo_file: Option<&str>) -> Result { }) } +/// convert dependencies from the TOML view fn get_dependencies(table: Option<&Value>) -> Result, Error> { let mut dependencies = vec![]; if let Some(table) = table { @@ -89,6 +96,7 @@ fn get_dependencies(table: Option<&Value>) -> Result, Error> { Ok(dependencies) } +/// Because strings in the toml are surrounded by double quotes fn strip_first_last(text: String) -> String{ text[1..text.len()-1].into() } \ No newline at end of file diff --git a/src/main.rs b/src/main.rs index 4b57b4b..dff755d 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,5 +1,6 @@ use anyhow::Error; +/// sample main that will be replaced by a generic one later fn main() -> anyhow::Result<(), Error> { let project = jargo::load_project(Some("tests/sample_project/Jargo.toml"))?; jargo::deploader::load_artifacts(&project.test_dependencies)?; diff --git a/src/pom/model.rs b/src/pom/model.rs index 4e16d46..564d634 100644 --- a/src/pom/model.rs +++ b/src/pom/model.rs @@ -1,6 +1,7 @@ use strong_xml::{XmlRead}; /// The Maven variant to parse poms +/// These structs is directly modelled after the XML because that is what strong-xml plugin requires #[derive(XmlRead, PartialEq, Debug)] #[xml(tag = "project")] pub struct Pom {