From 0615ea653c27a9e15ed4cb0d40fd00ae3f36048a Mon Sep 17 00:00:00 2001
From: Schrottkatze <git@schrottkatze.de>
Date: Fri, 19 Jan 2024 09:51:48 +0100
Subject: [PATCH] app(doc): well... write the docs

---
 crates/app/src/config.rs             | 11 +++++++++++
 crates/app/src/config/cli.rs         |  3 +++
 crates/app/src/config/config_file.rs |  7 ++-----
 crates/app/src/error_reporting.rs    |  7 ++++++-
 crates/app/src/welcome_msg.rs        |  3 +++
 5 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/crates/app/src/config.rs b/crates/app/src/config.rs
index f68fa34..9f2b15a 100644
--- a/crates/app/src/config.rs
+++ b/crates/app/src/config.rs
@@ -14,6 +14,7 @@ pub struct Config {
 }
 
 impl Config {
+    /// Get the configs from all possible places (args, file, env...)
     pub fn read() -> Self {
         let args = Args::parse();
         let config_path = if let Some(config_path) = args.config_path {
@@ -22,6 +23,7 @@ impl Config {
             find_config_file()
         };
 
+        // try to read a maybe existing config file
         let file_config = if let Ok(config_path) = config_path {
             let file_config = Configs::read(config_path);
 
@@ -52,13 +54,22 @@ impl Config {
 }
 
 pub mod error {
+    /// Errors that can occur when reading configs
     #[derive(Debug)]
     pub enum ConfigError {
+        /// The config dir doesn't exist
         NoConfigDir,
+        /// We didn't find a config file in the config dir
         NoConfigFileFound,
+        /// An io error happened while reading/opening it!
         IoError(std::io::Error),
+        /// The given extension (via an argument) isn't known.
+        ///
+        /// Occurs if the extension is neither `.json` nor `.ron` (including if there is no extension, in which case this will be `None`).
         UnknownExtension(Option<String>),
+        /// Wrapper around an `Error` from `serde_json`
         SerdeJsonError(serde_json::Error),
+        /// Wrapper around a `SpannedError` from `ron`
         SerdeRonError(ron::error::SpannedError),
     }
 
diff --git a/crates/app/src/config/cli.rs b/crates/app/src/config/cli.rs
index 23f8ef1..92026a2 100644
--- a/crates/app/src/config/cli.rs
+++ b/crates/app/src/config/cli.rs
@@ -7,6 +7,9 @@ pub(crate) struct Args {
     /// Read this config file.
     #[arg(short, long)]
     pub config_path: Option<PathBuf>,
+    /// Turn off the startup message.
+    ///
+    /// The startup message is not constant and depends on the time.
     #[arg(long, env = "NO_STARTUP_MESSAGE", default_value = "false")]
     pub no_startup_message: bool,
 }
diff --git a/crates/app/src/config/config_file.rs b/crates/app/src/config/config_file.rs
index d454223..a0c4db1 100644
--- a/crates/app/src/config/config_file.rs
+++ b/crates/app/src/config/config_file.rs
@@ -11,7 +11,7 @@ use super::error::ConfigError;
 pub struct Configs {
     #[serde(default = "default_example_value")]
     pub example_value: i32,
-    #[serde(default = "default_no_startup_msg")]
+    #[serde(default)]
     pub no_startup_message: bool,
 }
 
@@ -20,10 +20,7 @@ fn default_example_value() -> i32 {
     43
 }
 
-fn default_no_startup_msg() -> bool {
-    false
-}
-
+/// Find the location of a config file and check if there is, in fact, a file
 pub(super) fn find_config_file() -> Result<PathBuf, ConfigError> {
     let Some(config_path) = dirs::config_dir() else {
         return Err(ConfigError::NoConfigDir);
diff --git a/crates/app/src/error_reporting.rs b/crates/app/src/error_reporting.rs
index f71e10d..33ffff6 100644
--- a/crates/app/src/error_reporting.rs
+++ b/crates/app/src/error_reporting.rs
@@ -2,16 +2,19 @@ use std::process;
 
 use ron::error::Position;
 
+/// Report an `Error` from the `serde_json` crate
 pub fn report_serde_json_err(src: &str, err: serde_json::Error) -> ! {
     report_serde_err(src, err.line(), err.column(), err.to_string())
 }
 
+/// Report a `SpannedError` from the `ron` crate
 pub fn report_serde_ron_err(src: &str, err: ron::error::SpannedError) -> ! {
     let Position { line, col } = err.position;
     report_serde_err(src, line, col, err.to_string())
 }
 
-pub fn report_serde_err(src: &str, line: usize, col: usize, msg: String) -> ! {
+/// Basic function for reporting serde type of errors
+fn report_serde_err(src: &str, line: usize, col: usize, msg: String) -> ! {
     use ariadne::{Label, Report, Source};
     let offset = try_reconstruct_loc(src, line, col);
 
@@ -24,6 +27,8 @@ pub fn report_serde_err(src: &str, line: usize, col: usize, msg: String) -> ! {
         .unwrap();
     process::exit(1);
 }
+
+/// Reconstruct a byte offset from the line + column numbers typical from serde crates
 fn try_reconstruct_loc(src: &str, line_nr: usize, col_nr: usize) -> usize {
     let (line_nr, col_nr) = (line_nr - 1, col_nr - 1);
 
diff --git a/crates/app/src/welcome_msg.rs b/crates/app/src/welcome_msg.rs
index c03c543..a3e15a3 100644
--- a/crates/app/src/welcome_msg.rs
+++ b/crates/app/src/welcome_msg.rs
@@ -1,11 +1,14 @@
 use time::{Month, OffsetDateTime};
 
+/// Print the startup message which changes depending on system time.
 pub fn print_startup_msg() {
     // now or fallback to utc
     let now = OffsetDateTime::now_local().unwrap_or_else(|_| OffsetDateTime::now_utc());
 
     if now.month() == Month::June {
+        // pride startup message
         println!("Hello, thanks for using iOwO and happy pride month!");
+        // TODO: proper link with explaination
         println!("Why pride month is important in {}", now.year());
     } else {
         println!("Hello, thanks for using iOwO! :3");