From d409e9d41142a1dc648ba83693de78447a17bfbf Mon Sep 17 00:00:00 2001
From: steven-omaha <35634100+steven-omaha@users.noreply.github.com>
Date: Thu, 23 Feb 2023 16:56:15 +0100
Subject: [PATCH] add docstrings

---
 crates/pacdef_core/src/action.rs         |  2 ++
 crates/pacdef_core/src/args.rs           |  5 +++++
 crates/pacdef_core/src/cmd.rs            |  2 ++
 crates/pacdef_core/src/grouping/group.rs |  3 +++
 crates/pacdef_core/src/grouping/mod.rs   | 10 ++++++++++
 crates/pacdef_core/src/path.rs           |  6 ++++--
 6 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/crates/pacdef_core/src/action.rs b/crates/pacdef_core/src/action.rs
index 92805d3..31ce1fa 100644
--- a/crates/pacdef_core/src/action.rs
+++ b/crates/pacdef_core/src/action.rs
@@ -1,5 +1,7 @@
 use pacdef_macros::Action;
 
+/// All actions the program can perform. Variants of the enum relate to
+/// the different subcommands.
 #[derive(Debug, Action)]
 pub enum Actions {
     Clean,
diff --git a/crates/pacdef_core/src/args.rs b/crates/pacdef_core/src/args.rs
index 5f2894e..75a2bc8 100644
--- a/crates/pacdef_core/src/args.rs
+++ b/crates/pacdef_core/src/args.rs
@@ -7,6 +7,8 @@ use path_absolutize::Absolutize;
 use crate::action::*;
 use crate::core::get_version_string;
 
+/// Build the `pacdef` argument parser, with subcommands for `version`,
+/// `group` and `package`.
 fn get_arg_parser() -> Command {
     let package_cmd = get_package_cmd();
     let group_cmd = get_group_cmd();
@@ -20,6 +22,7 @@ fn get_arg_parser() -> Command {
         .subcommands([package_cmd, group_cmd, version_cmd])
 }
 
+/// Build the `pacdef group` subcommand.
 fn get_group_cmd() -> Command {
     let edit = Command::new(EDIT)
         .about("edit one or more existing group files")
@@ -70,6 +73,7 @@ fn get_group_cmd() -> Command {
         .subcommands([edit, import, list, new, remove, show])
 }
 
+/// Build the `pacdef package` subcommand.
 fn get_package_cmd() -> Command {
     let sync = Command::new(SYNC)
         .about("install packages from all imported groups")
@@ -103,6 +107,7 @@ pub fn get() -> clap::ArgMatches {
     get_arg_parser().get_matches()
 }
 
+/// For each file argument, return the absolute path to the file.
 pub fn get_absolutized_file_paths(arg_match: &ArgMatches) -> Result<Vec<PathBuf>> {
     Ok(arg_match
         .get_many::<String>("files")
diff --git a/crates/pacdef_core/src/cmd.rs b/crates/pacdef_core/src/cmd.rs
index 74f3aed..0917e28 100644
--- a/crates/pacdef_core/src/cmd.rs
+++ b/crates/pacdef_core/src/cmd.rs
@@ -5,6 +5,8 @@ use anyhow::{anyhow, Context, Result};
 
 use crate::env::get_editor;
 
+/// Run the editor and pass the provided files as arguments. The workdir is set
+/// to the parent of the first file.
 pub fn run_edit_command(files: &[&Path]) -> Result<ExitStatus> {
     let mut cmd = Command::new(get_editor().context("getting suitable editor")?);
     cmd.current_dir(
diff --git a/crates/pacdef_core/src/grouping/group.rs b/crates/pacdef_core/src/grouping/group.rs
index d6065a1..b1b843f 100644
--- a/crates/pacdef_core/src/grouping/group.rs
+++ b/crates/pacdef_core/src/grouping/group.rs
@@ -137,6 +137,9 @@ impl Group {
         })
     }
 
+    /// Add the new `packages` to the group file under the section `section_header`. If
+    /// the section header does not yet exist, it is created. The packages are written
+    /// in the provided order immediately after the header.
     pub(crate) fn save_packages(&self, section_header: &str, packages: &[Package]) -> Result<()> {
         let mut content = read_to_string(&self.path)
             .with_context(|| format!("reading existing file contents from {:?}", &self.path))?;
diff --git a/crates/pacdef_core/src/grouping/mod.rs b/crates/pacdef_core/src/grouping/mod.rs
index 402217c..3a6c0ce 100644
--- a/crates/pacdef_core/src/grouping/mod.rs
+++ b/crates/pacdef_core/src/grouping/mod.rs
@@ -1,3 +1,13 @@
+/*!
+This module reflects the relationship between groups, sections / backends and
+packages.
+
+A ['Group'] contains one (strictly spoken zero, but this doesn't make sense) or
+more ['Section']s, which relate to individual backends. Each section contains
+one (strictly spoken zero) or more ['Package']s. On start-up `pacdef` will load
+all groups using ['Group::load'], which in turn will get all packages from all
+sections.
+*/
 mod group;
 mod package;
 mod section;
diff --git a/crates/pacdef_core/src/path.rs b/crates/pacdef_core/src/path.rs
index eb6c7ec..a3ffdf2 100644
--- a/crates/pacdef_core/src/path.rs
+++ b/crates/pacdef_core/src/path.rs
@@ -53,11 +53,13 @@ pub fn get_config_path() -> Result<PathBuf> {
     Ok(file)
 }
 
-/// Get the path to the pacdef config file. This is `$XDG_CONFIG_HOME/pacdef/pacdef.yaml`.
+/// Get the path to the pacdef config file from version 0.x. This is
+/// `$XDG_CONFIG_HOME/pacdef/pacdef.yaml`.
 ///
 /// # Errors
 ///
-/// This function returns an error if both `$XDG_CONFIG_HOME` and `$HOME` are undefined.
+/// This function returns an error if both `$XDG_CONFIG_HOME` and `$HOME` are
+/// undefined.
 pub fn get_config_path_old_version() -> Result<PathBuf> {
     let mut file = get_pacdef_base_dir().context("getting pacdef base dir for config file")?;
     file.push(CONFIG_FILE_NAME_OLD);