From e980c597f1eec1470ee33508f8f2de3a692e4743 Mon Sep 17 00:00:00 2001
From: Michael Zhang <mail@mzhang.io>
Date: Sun, 14 Feb 2021 06:27:13 -0600
Subject: [PATCH] Add some documentation

---
 Justfile      |  2 ++
 src/config.rs | 18 ++++++++++++++++++
 src/lib.rs    | 20 ++++++++++++++++++++
 src/mail.rs   |  6 ++++++
 src/main.rs   | 27 +++++----------------------
 src/ui/mod.rs |  3 +++
 6 files changed, 54 insertions(+), 22 deletions(-)
 create mode 100644 Justfile
 create mode 100644 src/lib.rs

diff --git a/Justfile b/Justfile
new file mode 100644
index 0000000..67907d4
--- /dev/null
+++ b/Justfile
@@ -0,0 +1,2 @@
+doc:
+    cargo doc --document-private-items
diff --git a/src/config.rs b/src/config.rs
index 41164a6..964f44d 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,3 +1,7 @@
+//! Module for setting up config files and watchers.
+//!
+//! One of the primary goals of panorama is to be able to always hot-reload configuration files.
+
 use std::fs::File;
 use std::sync::mpsc::{self, Receiver};
 use std::time::Duration;
@@ -9,14 +13,22 @@ use notify::{DebouncedEvent, RecommendedWatcher, RecursiveMode, Watcher};
 use tokio::sync::watch;
 use xdg::BaseDirectories;
 
+/// Alias for a MailConfig receiver.
 pub type ConfigWatcher = watch::Receiver<Option<MailConfig>>;
 
+/// Configuration
 #[derive(Default, Serialize, Deserialize, Clone, Debug)]
 pub struct MailConfig {
+    /// Host of the IMAP server (needs to be hostname for TLS)
     pub server: String,
+
+    /// Port of the IMAP server
     pub port: u16,
 
+    /// Username for authenticating to IMAP
     pub username: String,
+
+    /// Password for authenticating to IMAP
     pub password: String,
 }
 
@@ -46,6 +58,10 @@ async fn read_config(path: impl AsRef<Path>) -> Result<MailConfig> {
     Ok(config)
 }
 
+/// The inner loop of the watcher, which is responsible for taking events received by the watcher
+/// and trying to parse and return the config.
+///
+/// This exists so all errors are able to be caught in one go.
 async fn watcher_loop(
     fs_events: Receiver<DebouncedEvent>,
     config_tx: watch::Sender<Option<MailConfig>>,
@@ -67,6 +83,8 @@ async fn watcher_loop(
     Ok(())
 }
 
+/// Start the entire config watcher system, and return a [ConfigWatcher][self::ConfigWatcher],
+/// which is a cloneable receiver of config update events.
 pub fn spawn_config_watcher() -> Result<ConfigWatcher> {
     let (_watcher, config_rx) = start_watcher()?;
     let (config_tx, config_update) = watch::channel(None);
diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..84b6f59
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,20 @@
+//! Panorama
+//! ===
+
+#![deny(missing_docs)]
+
+#[macro_use]
+extern crate anyhow;
+#[macro_use]
+extern crate crossterm;
+#[macro_use]
+extern crate log;
+#[macro_use]
+extern crate serde;
+
+pub mod config;
+pub mod mail;
+pub mod ui;
+
+/// A cloneable type that allows sending an exit-"signal" to stop the application.
+pub type ExitSender = tokio::sync::oneshot::Sender<()>;
diff --git a/src/mail.rs b/src/mail.rs
index 502bb81..92b2d23 100644
--- a/src/mail.rs
+++ b/src/mail.rs
@@ -1,3 +1,5 @@
+//! Mail
+
 use std::collections::HashMap;
 use std::fmt::Display;
 use std::sync::Arc;
@@ -24,8 +26,12 @@ use tokio_util::codec::{Decoder, LinesCodec, LinesCodecError};
 
 use crate::config::{MailConfig, ConfigWatcher};
 
+/// Command sent to the mail thread by something else (i.e. UI)
 pub enum MailCommand {
+    /// Refresh the list
     Refresh,
+
+    /// Send a raw command
     Raw(Command),
 }
 
diff --git a/src/main.rs b/src/main.rs
index 0013768..e329e6e 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,16 +1,3 @@
-#[macro_use]
-extern crate anyhow;
-#[macro_use]
-extern crate crossterm;
-#[macro_use]
-extern crate log;
-#[macro_use]
-extern crate serde;
-
-mod config;
-mod mail;
-mod ui;
-
 use std::fs::File;
 use std::io::Read;
 use std::path::PathBuf;
@@ -20,10 +7,7 @@ use futures::future::TryFutureExt;
 use structopt::StructOpt;
 use tokio::sync::{mpsc, oneshot};
 use xdg::BaseDirectories;
-
-use crate::config::{spawn_config_watcher, MailConfig};
-
-type ExitSender = oneshot::Sender<()>;
+use panorama::config::{spawn_config_watcher, MailConfig};
 
 #[derive(Debug, StructOpt)]
 #[structopt(author, about)]
@@ -48,7 +32,6 @@ async fn main() -> Result<()> {
     let xdg = BaseDirectories::new()?;
     let config_update = spawn_config_watcher()?;
 
-    let config = MailConfig::default();
     // let config: MailConfig = {
     //     let config_path = opt
     //         .config_path
@@ -74,10 +57,6 @@ async fn main() -> Result<()> {
     Ok(())
 }
 
-fn report_err(err: anyhow::Error) {
-    error!("error: {:?}", err);
-}
-
 fn setup_logger(opt: &Opt) -> Result<()> {
     let mut fern = fern::Dispatch::new()
         .format(|out, message, record| {
@@ -98,3 +77,7 @@ fn setup_logger(opt: &Opt) -> Result<()> {
     fern.apply()?;
     Ok(())
 }
+
+fn report_err(err: anyhow::Error) {
+    log::error!("error: {:?}", err);
+}
diff --git a/src/ui/mod.rs b/src/ui/mod.rs
index 32e5cfa..ad13c42 100644
--- a/src/ui/mod.rs
+++ b/src/ui/mod.rs
@@ -1,3 +1,5 @@
+//! UI
+
 mod table;
 
 use std::io::Write;
@@ -23,6 +25,7 @@ const FRAME: Duration = Duration::from_millis(20);
 #[derive(Copy, Clone)]
 pub struct Rect(u16, u16, u16, u16);
 
+/// UI entrypoint.
 pub async fn run_ui(mut w: impl Write, exit: ExitSender) -> Result<()> {
     execute!(w, cursor::Hide, terminal::EnterAlternateScreen)?;
     terminal::enable_raw_mode()?;