doc: added some documentation

Not very much, just enough to not be literally nothing.

Signed-off-by: Christina Sørensen <christina@cafkafk.com>

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;

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)
+/// An enum containing flags that change behaviour of repos and categories
-// ...because premature optimization is the root of all evil!
-//
-// it's time
-
 #[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<String, Category>,
+    /// A vector containing links
     pub links: Vec<Links>,
 }
 
@@ -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<F>(&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<SeriesItem>) {
+    ///
+    /// # Usage
+    ///
+    /// Here is an example of how an associated method could use this function.
+    ///
+    /// ```
+    /// let series: Vec<SeriesItem> = 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<SeriesItem>) {
         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 */

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

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;

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()

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"