Some renaming, restructuring, and documentation

src/background.rs

@@ -1,4 +1,4 @@
-//! Background monitoring for file-changes.
+//! Background monitoring for file changes.
 //!
 //! Whenever a file changes, we want to regenerate the HTML and send it to the UI for rendering to
 //! the user. This is done with the `init_update_loop` function.

src/input.rs

@@ -1,7 +1,7 @@
-//! Input handling.
+//! Input and config handling.
 //!
-//! Currently, this only includes handling command-line options. Potentially the place to handle
-//! any other type of configuration and input to the application.
+//! This includes command-line options and settings from the YAML config. Potentially the place to
+//! handle any other type of configuration and input to the application.
 
 use std::fs::File;
 use std::io;
@@ -18,7 +18,7 @@ use tempfile::NamedTempFile;
 use crate::assets::HIGHLIGHT_JS_VERSION;
 use crate::ui::action::Action;
 
-/// Command-line options. Managed by StructOpt.
+/// Command-line options. Managed by [`structopt`].
 #[derive(Debug, StructOpt)]
 pub struct Options {
     /// Activates debug logging
@@ -45,7 +45,7 @@ pub struct Options {
 }
 
 impl Options {
-    /// Creates a new instance by parsing input args. Apart from just running StructOpt's
+    /// Creates a new instance by parsing input args. Apart from just running [`structopt`]'s
     /// initialization, it also adds some additional information to the description that depends on
     /// the current environment.
     ///
@@ -107,21 +107,25 @@ pub struct Config {
     ///
     pub editor_command: Vec<String>,
 
-    /// Custom mappings. Each entry can contain three keys:
-    ///
-    /// - `key_char` or `key_name`: A descriptor, passed along to [`gdk::keys::Key::from_unicode`]
-    ///   or [`gdk::keys::Key::from_name`] respectively.
-    /// - `modifiers`: A list of modifiers, either "control", "shift", or "alt".
-    /// - `action`: See [`crate::ui::action::Action`].
-    ///
+    /// Custom mappings. See documentation of [`MappingDefinition`] for details.
     pub mappings: Vec<MappingDefinition>,
 }
 
+/// A single description of a mapping from a keybinding to a UI action. The fields `key_char` and
+/// `key_name` are exclusive, which is validated in [`crate::ui::action::Keymaps`].
+///
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct MappingDefinition {
+    /// A descriptor, passed along to [`gdk::keys::Key::from_unicode`]
     pub key_char: Option<char>,
+
+    /// A descriptor, passed along to [`gdk::keys::Key::from_name`]
     pub key_name: Option<String>,
+
+    /// A list of key modifiers, either "control", "shift", or "alt"
     pub modifiers: Vec<String>,
+
+    /// The action mapped to this key combination
     pub action: Action,
 }
 

src/main.rs

@@ -44,7 +44,7 @@ fn run(config: &Config, options: &Options) -> anyhow::Result<()> {
 }
 
 fn launch_file_picker() -> anyhow::Result<PathBuf> {
-    ui::file_picker::FilePicker::new().run().ok_or_else(|| {
+    ui::dialogs::FilePicker::new().run().ok_or_else(|| {
         anyhow!("Please provide a markdown file to render or call the program with - to read from STDIN")
     })
 }

src/markdown.rs

@@ -1,6 +1,6 @@
 //! Markdown rendering.
 //!
-//! Uses the `pulldown_cmark` crate with Github-flavored markdown options enabled. Extracts
+//! Uses the [`pulldown_cmark`] crate with Github-flavored markdown options enabled. Extracts
 //! languages used in code blocks for highlighting purposes.
 
 use std::fs;

src/ui/action.rs

@@ -1,4 +1,4 @@
-//! Actions on the UI triggered by keybindings
+//! Actions on the UI triggered by keybindings.
 
 use std::collections::HashMap;
 
@@ -15,38 +15,38 @@ pub enum Action {
     /// Placeholder action to allow unmapping keys
     Noop,
 
-    /// Scroll up by a small step
+    /// Scroll up by a small step. Default: `k`
     SmallScrollUp,
-    /// Scroll down by a small step
+    /// Scroll down by a small step. Default: `j`
     SmallScrollDown,
 
-    /// Scroll up by a large step
+    /// Scroll up by a large step. Default: `K`
     BigScrollUp,
-    /// Scroll down by a large step
+    /// Scroll down by a large step. Default: `J`
     BigScrollDown,
 
-    /// Scroll to the top of the document
+    /// Scroll to the top of the document. Default: `g`
     ScrollToTop,
-    /// Scroll to the bottom of the document
+    /// Scroll to the bottom of the document. Default: `G`
     ScrollToBottom,
 
-    /// Quit the entire application
+    /// Quit the entire application. Default: `ctrl+q`
     Quit,
 
-    /// Launch an editor instance if it's configured
+    /// Launch an editor instance if it's configured. Default: `e`
     LaunchEditor,
     /// Exec the current process into an editor instance if it's configured (and it's possible on
-    /// the OS)
+    /// the OS). Default: `E`
     ExecEditor,
 
-    /// Zoom the browser in by 10%
+    /// Zoom the browser in by 10%. Default: `+`
     ZoomIn,
-    /// Zoom the browser out by 10%
+    /// Zoom the browser out by 10%. Default: `-`
     ZoomOut,
-    /// Reset the zoom level to the configured starting point
+    /// Reset the zoom level to the configured starting point. Default: `=`
     ZoomReset,
 
-    /// Show a help popup
+    /// Show a help popup. Default: `F1`
     ShowHelp,
 }
 

src/ui/browser.rs

@@ -1,4 +1,4 @@
-//! A container for the `Browser` struct
+//! A container for the `Browser` struct that wraps the [`webkit2gtk::WebView`].
 
 use std::time::Instant;
 
@@ -12,7 +12,7 @@ use webkit2gtk::{WebContext, WebView};
 use crate::assets::PageState;
 use crate::input::Config;
 
-/// A thin layer on top of `webkit2gtk::WebView` to put helper methods into.
+/// A thin layer on top of [`webkit2gtk::WebView`] to put helper methods into.
 ///
 #[derive(Clone)]
 pub struct Browser {
@@ -38,12 +38,12 @@ impl Browser {
         window.add(&self.webview);
     }
 
-    /// Delegates to `webkit2gtk::WebView`
+    /// Delegates to [`webkit2gtk::WebView`]
     pub fn load_uri(&self, uri: &str) {
         self.webview.load_uri(uri);
     }
 
-    /// Delegates to `webkit2gtk::WebView`
+    /// Delegates to [`webkit2gtk::WebView`]
     pub fn reload(&self) {
         self.webview.reload();
     }
@@ -56,7 +56,7 @@ impl Browser {
         debug!("Zoom level set to: {}", zoom_level);
     }
 
-    /// Decrease zoom level by ~10%, down till 20% or so.
+    /// Decrease zoom level by ~10%, down until 20% or so.
     ///
     pub fn zoom_out(&self) {
         let zoom_level = self.webview.zoom_level();

src/ui/file_picker.rs → src/ui/dialogs.rs

@@ -1,9 +1,11 @@
-//! A container for the `FilePicker` struct
+//! Modal dialogs.
 
 use std::path::PathBuf;
 
 use gtk::prelude::*;
 
+use crate::input::Config;
+
 /// A popup to choose a file if it wasn't provided on the command-line.
 ///
 pub struct FilePicker(gtk::FileChooserDialog);
@@ -52,3 +54,28 @@ impl FilePicker {
 impl Drop for FilePicker {
     fn drop(&mut self) { self.0.close(); }
 }
+
+/// Open a popup that renders documentation for all the default keyboard and mouse mappings.
+///
+pub fn open_help_dialog(window: &gtk::Window) -> gtk::ResponseType {
+    use gtk::{DialogFlags, MessageType, ButtonsType};
+
+    let dialog = gtk::MessageDialog::new(
+        Some(window),
+        DialogFlags::MODAL | DialogFlags::DESTROY_WITH_PARENT,
+        MessageType::Info,
+        ButtonsType::Close,
+        ""
+    );
+
+    let content = format!{
+        include_str!("../../res/help_popup.html"),
+        yaml_path = Config::yaml_path().display(),
+        css_path = Config::css_path().display(),
+    };
+
+    dialog.set_markup(&content);
+    dialog.connect_response(|d, _response| d.close());
+
+    dialog.run()
+}

src/ui/mod.rs

@@ -2,7 +2,7 @@
 
 pub mod action;
 pub mod browser;
-pub mod file_picker;
+pub mod dialogs;
 
 use std::path::{PathBuf, Path};
 use std::process::Command;
@@ -14,8 +14,9 @@ use pathbuftools::PathBufTools;
 use crate::assets::Assets;
 use crate::input::{InputFile, Config};
 use crate::markdown::RenderedContent;
-use crate::ui::browser::Browser;
 use crate::ui::action::{Action, Keymaps};
+use crate::ui::browser::Browser;
+use crate::ui::dialogs::open_help_dialog;
 
 /// The container for all the GTK widgets of the app -- window, webview, etc.
 /// All of these are reference-counted, so should be cheap to clone.
@@ -152,7 +153,7 @@ impl App {
                 Action::ZoomIn    => browser.zoom_in(),
                 Action::ZoomOut   => browser.zoom_out(),
                 Action::ZoomReset => browser.zoom_reset(),
-                Action::ShowHelp  => { build_help_dialog(window).run(); },
+                Action::ShowHelp  => { open_help_dialog(window); },
                 Action::Quit      => gtk::main_quit(),
                 _ => (),
             }
@@ -233,26 +234,3 @@ fn build_editor_command(editor_command: &[String], file_path: &Path) -> Option<C
 
     Some(command)
 }
-
-fn build_help_dialog(window: &gtk::Window) -> gtk::MessageDialog {
-    use gtk::{DialogFlags, MessageType, ButtonsType};
-
-    let dialog = gtk::MessageDialog::new(
-        Some(window),
-        DialogFlags::MODAL | DialogFlags::DESTROY_WITH_PARENT,
-        MessageType::Info,
-        ButtonsType::Close,
-        ""
-    );
-
-    let content = format!{
-        include_str!("../../res/help_popup.html"),
-        yaml_path = Config::yaml_path().display(),
-        css_path = Config::css_path().display(),
-    };
-
-    dialog.set_markup(&content);
-    dialog.connect_response(|d, _response| d.close());
-
-    dialog
-}