added rustdocs for most functions/structs

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<PathNode>, Vec<PathNode>),
     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)?;
 

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<Config> = OnceLock::new();
 
+/// default config
 pub fn config() -> &'static Config {
     CONFIG.get_or_init(|| {
         let user_home = home::home_dir().unwrap();

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

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<pom::model::Dependency> for Artifact {
     fn from(value: pom::model::Dependency) -> Self {
         Artifact {
@@ -37,6 +40,8 @@ impl From<pom::model::Dependency> for Artifact {
 }
 
 impl Artifact {
+
+    /// Convert from TOML view
     pub fn from_table_entry(name_group: &str, version: String) -> Result<Self, Error>{
         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<Project, Error> {
     let jargo = Path::new(jargo_file.unwrap_or("./Jargo.toml"));
 
@@ -74,6 +80,7 @@ pub fn load_project(jargo_file: Option<&str>) -> Result<Project, Error> {
     })
 }
 
+/// convert dependencies from the TOML view
 fn get_dependencies(table: Option<&Value>) -> Result<Vec<Artifact>, Error> {
     let mut dependencies = vec![];
     if let Some(table) = table {
@@ -89,6 +96,7 @@ fn get_dependencies(table: Option<&Value>) -> Result<Vec<Artifact>, 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()
 }

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)?;

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 {