From a52cc15f8e4fd51b15b3dbce093df206aaf1495c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christina=20S=C3=B8rensen?= Date: Sat, 1 Jul 2023 10:40:45 +0200 Subject: [PATCH] doc: added some documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Not very much, just enough to not be literally nothing. Signed-off-by: Christina Sørensen --- src/cli.rs | 2 ++ src/git.rs | 54 ++++++++++++++++++++++++++++++++++++-------- src/main.rs | 21 +++++++++++++++++ src/utils.rs | 2 ++ src/utils/dir.rs | 8 +++++++ src/utils/strings.rs | 5 ++++ 6 files changed, 82 insertions(+), 10 deletions(-) diff --git a/src/cli.rs b/src/cli.rs index b5fa2cc..84684e7 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -13,6 +13,8 @@ // // You should have received a copy of the GNU General Public License // along with this program. If not, see https://www.gnu.org/gpl-3.0.html. +// +//! Handles command line input use crate::utils::dir::home_dir; use crate::utils::strings::INTERACTIVE_NOTICE; diff --git a/src/git.rs b/src/git.rs index 7db9a4d..2c0ac17 100644 --- a/src/git.rs +++ b/src/git.rs @@ -13,6 +13,8 @@ // // You should have received a copy of the GNU General Public License // along with this program. If not, see https://www.gnu.org/gpl-3.0.html. +// +//! Git repositories use log::{debug, error, info, trace, warn}; use serde::{Deserialize, Serialize}; @@ -23,25 +25,29 @@ use std::os::unix::fs::symlink; use std::path::Path; use std::{fs, process::Command}; -// why not make it O(log n) instead of a vec that's /only/ O(n) -// ...because premature optimization is the root of all evil! -// -// it's time - +/// An enum containing flags that change behaviour of repos and categories #[derive(PartialOrd, Ord, PartialEq, Eq, Serialize, Deserialize, Debug)] pub enum RepoFlags { + /// If push is set, the repository should respond to the push subcommand Push, + /// If clone is set, the repository should respond to the clone subcommand Clone, + /// If pull is set, the repository should respond to the pull subcommand Pull, } /// Represents the config.toml file. +/// +/// For diagrams of the underlying architecture, consult ARCHITECHTURE.md +/// +/// #[derive(PartialEq, Debug, Serialize, Deserialize)] pub struct Config { /// map of all categories /// /// Key should conceptually be seen as the name of the category. pub categories: HashMap, + /// A vector containing links pub links: Vec, } @@ -60,6 +66,7 @@ pub struct Category { /// Contain fields for a single link. #[derive(PartialEq, Debug, Serialize, Deserialize)] pub struct Links { + /// The name of the link pub name: String, pub rx: String, pub tx: String, @@ -254,6 +261,11 @@ impl Config { } } } + /// Runs associated function on all repos in config + /// + /// TODO: need to be made over a generic repo type + /// + /// fn on_all_spinner(&self, op: &str, f: F) where F: Fn(&GitRepo) -> bool, @@ -287,7 +299,33 @@ impl Config { /// However, at 6:24, we're so ready! Let's go! /// /// Fun fact: only the last element of a tuple must have a dynamically typed size - fn series_on_all(&self, closures: Vec) { + /// + /// # Usage + /// + /// Here is an example of how an associated method could use this function. + /// + /// ``` + /// let series: Vec = vec![ + /// SeriesItem { + /// operation: "pull", + /// closure: Box::new(move |repo: &GitRepo| repo.pull()), + /// }, + /// SeriesItem { + /// operation: "add", + /// closure: Box::new(move |repo: &GitRepo| repo.add_all()), + /// }, + /// SeriesItem { + /// operation: "commit", + /// closure: Box::new(move |repo: &GitRepo| repo.commit()), + /// }, + /// SeriesItem { + /// operation: "push", + /// closure: Box::new(move |repo: &GitRepo| repo.push()), + /// }, + /// ]; + /// self.series_on_all(series); + /// ``` + pub fn series_on_all(&self, closures: Vec) { for (_, category) in self.categories.iter() { for (_, repo) in category.repos.iter() { for instruction in closures.iter() { @@ -353,10 +391,6 @@ impl Config { }, ]; self.series_on_all(series); - // self.on_all_spinner("pull", |repo| repo.pull()); - // self.on_all_spinner("add", |repo| repo.add_all()); - // self.on_all_spinner("commit", |repo| repo.commit_with_msg(msg)); - // self.on_all_spinner("push", |repo| repo.push()); } /* LINK RELATED */ diff --git a/src/main.rs b/src/main.rs index 2da0ea7..f173e6e 100644 --- a/src/main.rs +++ b/src/main.rs @@ -13,6 +13,22 @@ // // You should have received a copy of the GNU General Public License // along with this program. If not, see https://www.gnu.org/gpl-3.0.html. +// +//! A Rust GitOps/symlinkfarm orchestrator inspired by GNU Stow. +//! +//! # What is? +//! +//! A Rust GitOps/symlinkfarm orchestrator inspired by GNU Stow. Useful for dealing +//! with "dotfiles", and with git support as a first class feature. Configuration is +//! done throug a single yaml file, giving it a paradigm that should bring joy to +//! those that use declarative operating systems and package managers. +//! +//! Although this isn't really a case where it matters *that* much for performance, +//! being written in rust instead of e.g. /janky/ scripting languages does also mean +//! it is snappy and reliable, and the /extensive/ testing helps ensure regressions +//! aren't introduced. +//! +//! That said, we're in 0.0.Z, *here be dragons* for now. #![feature(unsized_tuple_coercion)] extern crate log; @@ -29,9 +45,14 @@ use cli::{Args, Commands}; use git::Config; use clap::Parser; + #[allow(unused)] use log::{debug, error, info, trace, warn}; +/// The main loop of the binary +/// +/// Here, we handle parsing the configuration file, as well as matching commands +/// to the relavant operations. fn main() { pretty_env_logger::init(); let args = Args::parse(); diff --git a/src/utils.rs b/src/utils.rs index 6c70879..e747f7f 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -13,6 +13,8 @@ // // You should have received a copy of the GNU General Public License // along with this program. If not, see https://www.gnu.org/gpl-3.0.html. +// +//! Sublibrary for useful functions pub mod dir; pub mod strings; diff --git a/src/utils/dir.rs b/src/utils/dir.rs index b617c3f..1530bab 100644 --- a/src/utils/dir.rs +++ b/src/utils/dir.rs @@ -13,6 +13,8 @@ // // You should have received a copy of the GNU General Public License // along with this program. If not, see https://www.gnu.org/gpl-3.0.html. +// +//! Nice helpers for dealing with filesystem environment. #![feature(stmt_expr_attributes)] use log::{debug, error, info, trace, warn}; @@ -20,6 +22,9 @@ use log::{debug, error, info, trace, warn}; use std::env; use std::path::Path; +/// Returns the users current dir +/// +/// Does not work on Windows pub fn current_dir() -> String { #[allow(deprecated)] // NOTE we don't care about windows , we don't support it env::current_dir() @@ -29,6 +34,9 @@ pub fn current_dir() -> String { .expect("Failed to turn home_dir into a valid string") } +/// Returns the users home dir +/// +/// Does not work on Windows pub fn home_dir() -> String { #[allow(deprecated)] // NOTE we don't care about windows , we don't support it env::home_dir() diff --git a/src/utils/strings.rs b/src/utils/strings.rs index fd0c38a..05972d8 100644 --- a/src/utils/strings.rs +++ b/src/utils/strings.rs @@ -13,6 +13,11 @@ // // You should have received a copy of the GNU General Public License // along with this program. If not, see https://www.gnu.org/gpl-3.0.html. +// +//! Module for chunk of text +//! +//! Ideally, at a VERY long term scale, this should be a nice pattern for +//! possible translations. /// Contains the notice for interactive programs from the GPLv3's "How to Apply /// These Terms to Your New Programs"