more notes

src/args.rs

@@ -10,6 +10,8 @@ use std::{error::Error, fmt, result::Result};
 #[cfg(not(test))]
 use atty;
 
+/// The error returned if something goes awry while parsing the
+/// command line arguments.
 #[derive(Debug)]
 pub struct ArgError {
     details: String,

src/config.rs

@@ -16,7 +16,7 @@ const CONFIG_FILE: &str = "phetch.conf";
 /// Default start page.
 const DEFAULT_START: &str = "gopher://phetch/1/home";
 
-/// Default config
+/// Example of what a default phetch.conf would be.
 pub const DEFAULT_CONFIG: &str = "## default config file for the phetch gopher client
 ## gopher://phkt.io/1/phetch
 
@@ -36,6 +36,9 @@ wide no
 emoji no
 ";
 
+/// Not all the config options are available in the phetch.conf. We
+/// also use this struct to keep track of our session's overall state,
+/// such as the UI mode (Print, Run, Raw, etc).
 #[derive(Debug)]
 pub struct Config {
     pub start: String,
@@ -43,7 +46,6 @@ pub struct Config {
     pub tor: bool,
     pub wide: bool,
     pub emoji: bool,
-    pub cursor: bool,
     pub mode: ui::Mode, // can't be set in conf file
 }
 
@@ -55,7 +57,6 @@ impl Default for Config {
             tor: false,
             wide: false,
             emoji: false,
-            cursor: true,
             mode: ui::Mode::default(),
         }
     }

src/lib.rs

@@ -15,12 +15,19 @@ pub mod phetchdir;
 pub mod text;
 pub mod ui;
 
+/// Current version of phetch.
 pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+/// Current OS. Used to check for updates.
 pub const PLATFORM: &str = env!("PLATFORM");
+/// Git SHA of current build.
 pub const GIT_REF: &str = env!("GIT_REF");
+/// Date when this release was built.
 pub const BUILD_DATE: &str = env!("BUILD_DATE");
+/// Where to file issues. We try to catch and display all errors
+/// nicely, but if we have to crash we will try to show this.
 pub const BUG_URL: &str = "https://github.com/xvxx/phetch/issues/new";
 
+/// Whether we compiled with TLS support.
 #[cfg(not(feature = "disable-tls"))]
 pub const TLS_SUPPORT: &str = "enabled";
 #[cfg(feature = "disable-tls")]

src/main.rs

@@ -25,10 +25,7 @@ fn run() -> i32 {
         Mode::Version => return print_version(),
         Mode::Help => return print_usage(),
         Mode::NoTTY => return print_plain(&cfg.start, cfg.tls, cfg.tor),
-        Mode::Print => {
-            cfg.cursor = false;
-            cfg.wide = true;
-        }
+        Mode::Print => cfg.wide = true,
         _ => {}
     }
 

src/menu.rs

@@ -14,6 +14,12 @@ use crate::{
 use std::fmt;
 use termion::{clear, cursor};
 
+/// The Menu holds our Gopher Lines, a list of links, and maintains
+/// both where the cursor is on screen and which lines need to be
+/// drawn on screen. While the main UI can be used to prompt the user
+/// for input, the Menu maintains its own `input` for the "quick
+/// navigation" feature using number entry and the "incremental search"
+/// (over menu links) feature using text entry.
 pub struct Menu {
     pub url: String,          // gopher url
     pub lines: Vec<Line>,     // lines

src/text.rs

@@ -9,6 +9,8 @@ use crate::{
 use std::fmt;
 use termion::clear;
 
+/// The Text View holds the raw Gopher response as well as information
+/// about which lines should currently be displayed on screen.
 pub struct Text {
     url: String,
     raw_response: String,

src/ui.rs

@@ -44,9 +44,15 @@ use termion::{
 pub type Key = termion::event::Key;
 pub type Page = Box<dyn View>;
 
+/// How many lines to jump by when using page up/down.
 pub const SCROLL_LINES: usize = 15;
+/// How big the longest line can be, for the purposes of calculating
+/// margin sizes. We often draw longer lines than this and allow
+/// wrapping in text views.
 pub const MAX_COLS: usize = 77;
 
+/// UI is mainly concerned with drawing to the screen, managing the
+/// active Views/pages, and responding to user input.
 pub struct UI {
     views: Vec<Page>,         // loaded views
     focused: usize,           // currently focused view

src/ui/action.rs

@@ -4,15 +4,30 @@ use std::fmt;
 /// Views generate Actions in response to user input, which are
 /// processed by the UI.
 pub enum Action {
-    None,                                              // do nothing
-    Open(String, String),                              // open(title, url)
-    Keypress(Key),                                     // unknown keypress
-    Redraw,                                            // redraw everything
-    Draw(String),                                      // draw something on screen
-    Status(String),                                    // set the "status" line to something
-    Prompt(String, Box<dyn FnOnce(String) -> Action>), // query string, callback on success
-    List(Vec<Action>),                                 // do more than one action
-    Error(String),                                     // error message
+    /// Do nothing. Eg: Hit the down arrow but can't go down.
+    None,
+    /// Open a URL: open(title, url)
+    Open(String, String),
+    /// If the View doesn't know how to react, it returns the keypress.
+    Keypress(Key),
+    /// Redraw the screen. Can cause a flicker
+    Redraw,
+    /// Draw something on screen. This assumes you're using Goto(X,Y)
+    /// to control where exactly you're drawing it. Nothing else will
+    /// be redrawn.
+    Draw(String),
+    /// Set the "status" line to some text.
+    Status(String),
+    /// Show a prompt and ask for the user to input text.
+    /// The callback is passed what the user entered, if they type
+    /// something in and hit enter. If they cancel, the callback is
+    /// not run.
+    /// Prompt(Prompt Query, Callback)
+    Prompt(String, Box<dyn FnOnce(String) -> Action>),
+    /// Do more than one action.
+    List(Vec<Action>),
+    /// Display an error message.
+    Error(String),
 }
 
 impl Action {

src/ui/mode.rs

@@ -2,12 +2,25 @@
 /// Print doesn't show the cursor, among other things.
 #[derive(Debug, PartialEq, Copy, Clone)]
 pub enum Mode {
-    Run,     // url
-    Print,   // --print url
-    NoTTY,   // --print url | cat
-    Raw,     // --raw
-    Version, // --version
-    Help,    // --help
+    /// Default, interactive mode.
+    ///   phetch URL
+    Run,
+
+    /// Just print a rendered version of a URL.
+    ///   phetch --print URL
+    Print,
+    /// NoTTY, ie in a UNIX pipeline.
+    ///   phetch --print URL | cat
+    NoTTY,
+    /// Just print raw Gopher response.
+    ///   phetch --raw URL
+    Raw,
+    /// Show version info.
+    ///   phetch --version
+    Version,
+    /// Show command line help.
+    ///   phetch --help
+    Help,
 }
 
 impl Default for Mode {