Extend style guideline documentation

62 files changed, 1224 insertions, 1218 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1ab17fcc..82fba0f8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -99,6 +99,13 @@ All Alacritty changes are automatically verified by CI to conform to its rustfmt
 build is failing because of formatting issues, you can install rustfmt using `rustup component add
 rustfmt` and then format all code using `cargo fmt`.
 
+Unless otherwise specified, Alacritty follows the Rust compiler's style guidelines:
+
+https://rust-lang.github.io/api-guidelines
+
+All comments should be fully punctuated with a trailing period. This applies both to regular and
+documentation comments.
+
 # Release Process
 
 Alacritty's release process aims to provide stable and well tested releases without having to hold
diff --git a/alacritty/src/cli.rs b/alacritty/src/cli.rs
index 2137c9c8..5f6b7804 100644
--- a/alacritty/src/cli.rs
+++ b/alacritty/src/cli.rs
@@ -30,7 +30,7 @@ const CONFIG_PATH: &str = "%APPDATA%\\alacritty\\alacritty.yml";
 #[cfg(target_os = "macos")]
 const CONFIG_PATH: &str = "$HOME/.config/alacritty/alacritty.yml";
 
-/// Options specified on the command line
+/// Options specified on the command line.
 pub struct Options {
     pub live_config_reload: Option<bool>,
     pub print_events: bool,
@@ -241,8 +241,8 @@ impl Options {
 
         if let Some(mut args) = matches.values_of("command") {
             // The following unwrap is guaranteed to succeed.
-            // If 'command' exists it must also have a first item since
-            // Arg::min_values(1) is set.
+            // If `command` exists it must also have a first item since
+            // `Arg::min_values(1)` is set.
             let command = String::from(args.next().unwrap());
             let args = args.map(String::from).collect();
             options.command = Some(Shell::new_with_args(command, args));
diff --git a/alacritty/src/config/bindings.rs b/alacritty/src/config/bindings.rs
index d6520441..74e1be37 100644
--- a/alacritty/src/config/bindings.rs
+++ b/alacritty/src/config/bindings.rs
@@ -25,21 +25,21 @@ use serde_yaml::Value as SerdeValue;
 use alacritty_terminal::term::TermMode;
 use alacritty_terminal::vi_mode::ViMotion;
 
-/// Describes a state and action to take in that state
+/// Describes a state and action to take in that state.
 ///
-/// This is the shared component of `MouseBinding` and `KeyBinding`
+/// This is the shared component of `MouseBinding` and `KeyBinding`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Binding<T> {
-    /// Modifier keys required to activate binding
+    /// Modifier keys required to activate binding.
     pub mods: ModifiersState,
 
-    /// String to send to pty if mods and mode match
+    /// String to send to PTY if mods and mode match.
     pub action: Action,
 
-    /// Terminal mode required to activate binding
+    /// Terminal mode required to activate binding.
     pub mode: TermMode,
 
-    /// excluded terminal modes where the binding won't be activated
+    /// excluded terminal modes where the binding won't be activated.
     pub notmode: TermMode,
 
     /// This property is used as part of the trigger detection code.
@@ -48,10 +48,10 @@ pub struct Binding<T> {
     pub trigger: T,
 }
 
-/// Bindings that are triggered by a keyboard key
+/// Bindings that are triggered by a keyboard key.
 pub type KeyBinding = Binding<Key>;
 
-/// Bindings that are triggered by a mouse button
+/// Bindings that are triggered by a mouse button.
 pub type MouseBinding = Binding<MouseButton>;
 
 impl<T: Eq> Binding<T> {
@@ -68,19 +68,19 @@ impl<T: Eq> Binding<T> {
 
     #[inline]
     pub fn triggers_match(&self, binding: &Binding<T>) -> bool {
-        // Check the binding's key and modifiers
+        // Check the binding's key and modifiers.
         if self.trigger != binding.trigger || self.mods != binding.mods {
             return false;
         }
 
-        // Completely empty modes match all modes
+        // Completely empty modes match all modes.
         if (self.mode.is_empty() && self.notmode.is_empty())
             || (binding.mode.is_empty() && binding.notmode.is_empty())
         {
             return true;
         }
 
-        // Check for intersection (equality is required since empty does not intersect itself)
+        // Check for intersection (equality is required since empty does not intersect itself).
         (self.mode == binding.mode || self.mode.intersects(binding.mode))
             && (self.notmode == binding.notmode || self.notmode.intersects(binding.notmode))
     }
@@ -171,7 +171,7 @@ pub enum Action {
     /// Toggle fullscreen.
     ToggleFullscreen,
 
-    /// Toggle simple fullscreen on macos.
+    /// Toggle simple fullscreen on macOS.
     #[cfg(target_os = "macos")]
     ToggleSimpleFullscreen,
 
@@ -452,8 +452,7 @@ pub fn default_key_bindings() -> Vec<KeyBinding> {
             F20,    mods, ~TermMode::VI; Action::Esc(format!("\x1b[34;{}~", modifiers_code));
         ));
 
-        // We're adding the following bindings with `Shift` manually above, so skipping them here
-        // modifiers_code != Shift
+        // We're adding the following bindings with `Shift` manually above, so skipping them here.
         if modifiers_code != 2 {
             bindings.extend(bindings!(
                 KeyBinding;
@@ -525,7 +524,7 @@ pub fn platform_key_bindings() -> Vec<KeyBinding> {
     )
 }
 
-// Don't return any bindings for tests since they are commented-out by default
+// Don't return any bindings for tests since they are commented-out by default.
 #[cfg(test)]
 pub fn platform_key_bindings() -> Vec<KeyBinding> {
     vec![]
@@ -956,7 +955,7 @@ impl CommandWrapper {
     }
 }
 
-/// Newtype for implementing deserialize on glutin Mods
+/// Newtype for implementing deserialize on glutin Mods.
 ///
 /// Our deserialize impl wouldn't be covered by a derive(Deserialize); see the
 /// impl below.
diff --git a/alacritty/src/config/mod.rs b/alacritty/src/config/mod.rs
index bb05d980..f416039c 100644
--- a/alacritty/src/config/mod.rs
+++ b/alacritty/src/config/mod.rs
@@ -22,22 +22,22 @@ use crate::config::ui_config::UIConfig;
 
 pub type Config = TermConfig<UIConfig>;
 
-/// Result from config loading
+/// Result from config loading.
 pub type Result<T> = std::result::Result<T, Error>;
 
-/// Errors occurring during config loading
+/// Errors occurring during config loading.
 #[derive(Debug)]
 pub enum Error {
-    /// Config file not found
+    /// Config file not found.
     NotFound,
 
-    /// Couldn't read $HOME environment variable
+    /// Couldn't read $HOME environment variable.
     ReadingEnvHome(env::VarError),
 
-    /// io error reading file
+    /// io error reading file.
     Io(io::Error),
 
-    /// Not valid yaml or missing parameters
+    /// Not valid yaml or missing parameters.
     Yaml(serde_yaml::Error),
 }
 
@@ -96,7 +96,7 @@ impl From<serde_yaml::Error> for Error {
 /// 4. $HOME/.alacritty.yml
 #[cfg(not(windows))]
 pub fn installed_config() -> Option<PathBuf> {
-    // Try using XDG location by default
+    // Try using XDG location by default.
     xdg::BaseDirectories::with_prefix("alacritty")
         .ok()
         .and_then(|xdg| xdg.find_config_file("alacritty.yml"))
@@ -107,12 +107,12 @@ pub fn installed_config() -> Option<PathBuf> {
         })
         .or_else(|| {
             if let Ok(home) = env::var("HOME") {
-                // Fallback path: $HOME/.config/alacritty/alacritty.yml
+                // Fallback path: $HOME/.config/alacritty/alacritty.yml.
                 let fallback = PathBuf::from(&home).join(".config/alacritty/alacritty.yml");
                 if fallback.exists() {
                     return Some(fallback);
                 }
-                // Fallback path: $HOME/.alacritty.yml
+                // Fallback path: $HOME/.alacritty.yml.
                 let fallback = PathBuf::from(&home).join(".alacritty.yml");
                 if fallback.exists() {
                     return Some(fallback);
@@ -146,7 +146,7 @@ pub fn reload_from(path: &PathBuf) -> Result<Config> {
 fn read_config(path: &PathBuf) -> Result<Config> {
     let mut contents = fs::read_to_string(path)?;
 
-    // Remove UTF-8 BOM
+    // Remove UTF-8 BOM.
     if contents.starts_with('\u{FEFF}') {
         contents = contents.split_off(3);
     }
diff --git a/alacritty/src/config/monitor.rs b/alacritty/src/config/monitor.rs
index 8dc5379a..d91b2e4b 100644
--- a/alacritty/src/config/monitor.rs
+++ b/alacritty/src/config/monitor.rs
@@ -28,11 +28,11 @@ impl Monitor {
                     watcher(tx, Duration::from_millis(10)).expect("Unable to spawn file watcher");
                 let config_path = ::std::fs::canonicalize(path).expect("canonicalize config path");
 
-                // Get directory of config
+                // Get directory of config.
                 let mut parent = config_path.clone();
                 parent.pop();
 
-                // Watch directory
+                // Watch directory.
                 watcher
                     .watch(&parent, RecursiveMode::NonRecursive)
                     .expect("watch alacritty.yml dir");
diff --git a/alacritty/src/config/mouse.rs b/alacritty/src/config/mouse.rs
index b7832b4a..9192aba9 100644
--- a/alacritty/src/config/mouse.rs
+++ b/alacritty/src/config/mouse.rs
@@ -24,11 +24,11 @@ pub struct Mouse {
 #[serde(default)]
 #[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
 pub struct Url {
-    // Program for opening links
+    /// Program for opening links.
     #[serde(deserialize_with = "deserialize_launcher")]
     pub launcher: Option<CommandWrapper>,
 
-    // Modifier used to open links
+    /// Modifier used to open links.
     #[serde(deserialize_with = "failure_default")]
     modifiers: ModsWrapper,
 }
@@ -47,10 +47,10 @@ where
 {
     let default = Url::default().launcher;
 
-    // Deserialize to generic value
+    // Deserialize to generic value.
     let val = serde_yaml::Value::deserialize(deserializer)?;
 
-    // Accept `None` to disable the launcher
+    // Accept `None` to disable the launcher.
     if val.as_str().filter(|v| v.to_lowercase() == "none").is_some() {
         return Ok(None);
     }
diff --git a/alacritty/src/config/ui_config.rs b/alacritty/src/config/ui_config.rs
index 13a3b04e..49e54e05 100644
--- a/alacritty/src/config/ui_config.rs
+++ b/alacritty/src/config/ui_config.rs
@@ -11,11 +11,11 @@ pub struct UIConfig {
     #[serde(default, deserialize_with = "failure_default")]
     pub mouse: Mouse,
 
-    /// Keybindings
+    /// Keybindings.
     #[serde(default = "default_key_bindings", deserialize_with = "deserialize_key_bindings")]
     pub key_bindings: Vec<KeyBinding>,
 
-    /// Bindings for the mouse
+    /// Bindings for the mouse.
     #[serde(default = "default_mouse_bindings", deserialize_with = "deserialize_mouse_bindings")]
     pub mouse_bindings: Vec<MouseBinding>,
 }
@@ -63,7 +63,7 @@ where
 {
     let values = Vec::<serde_yaml::Value>::deserialize(deserializer)?;
 
-    // Skip all invalid values
+    // Skip all invalid values.
     let mut bindings = Vec::with_capacity(values.len());
     for value in values {
         match Binding::<T>::deserialize(value) {
@@ -74,7 +74,7 @@ where
         }
     }
 
-    // Remove matching default bindings
+    // Remove matching default bindings.
     for binding in bindings.iter() {
         default.retain(|b| !b.triggers_match(binding));
     }
diff --git a/alacritty/src/cursor.rs b/alacritty/src/cursor.rs
index 253fdaa7..4d33e016 100644
--- a/alacritty/src/cursor.rs
+++ b/alacritty/src/cursor.rs
@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Helpers for creating different cursor glyphs from font metrics
+//! Helpers for creating different cursor glyphs from font metrics.
 
 use std::cmp;
 
@@ -28,13 +28,13 @@ pub fn get_cursor_glyph(
     is_wide: bool,
     cursor_thickness: f64,
 ) -> RasterizedGlyph {
-    // Calculate the cell metrics
+    // Calculate the cell metrics.
     let height = metrics.line_height as i32 + i32::from(offset_y);
     let mut width = metrics.average_advance as i32 + i32::from(offset_x);
 
     let line_width = cmp::max((cursor_thickness * f64::from(width)).round() as i32, 1);
 
-    // Double the cursor width if it's above a double-width glyph
+    // Double the cursor width if it's above a double-width glyph.
     if is_wide {
         width *= 2;
     }
@@ -48,12 +48,12 @@ pub fn get_cursor_glyph(
     }
 }
 
-// Returns a custom underline cursor character
+/// Return a custom underline cursor character.
 pub fn get_underline_cursor_glyph(width: i32, line_width: i32) -> RasterizedGlyph {
-    // Create a new rectangle, the height is relative to the font width
+    // Create a new rectangle, the height is relative to the font width.
     let buf = vec![255u8; (width * line_width * 3) as usize];
 
-    // Create a custom glyph with the rectangle data attached to it
+    // Create a custom glyph with the rectangle data attached to it.
     RasterizedGlyph {
         c: ' ',
         top: line_width,
@@ -64,7 +64,7 @@ pub fn get_underline_cursor_glyph(width: i32, line_width: i32) -> RasterizedGlyp
     }
 }
 
-// Returns a custom beam cursor character
+/// Return a custom beam cursor character.
 pub fn get_beam_cursor_glyph(height: i32, line_width: i32) -> RasterizedGlyph {
     // Create a new rectangle that is at least one pixel wide
     let buf = vec![255u8; (line_width * height * 3) as usize];
@@ -80,9 +80,9 @@ pub fn get_beam_cursor_glyph(height: i32, line_width: i32) -> RasterizedGlyph {
     }
 }
 
-// Returns a custom box cursor character
+/// Returns a custom box cursor character.
 pub fn get_box_cursor_glyph(height: i32, width: i32, line_width: i32) -> RasterizedGlyph {
-    // Create a new box outline rectangle
+    // Create a new box outline rectangle.
     let mut buf = Vec::with_capacity((width * height * 3) as usize);
     for y in 0..height {
         for x in 0..width {
@@ -98,15 +98,15 @@ pub fn get_box_cursor_glyph(height: i32, width: i32, line_width: i32) -> Rasteri
         }
     }
 
-    // Create a custom glyph with the rectangle data attached to it
+    // Create a custom glyph with the rectangle data attached to it.
     RasterizedGlyph { c: ' ', top: height, left: 0, height, width, buf: BitmapBuffer::RGB(buf) }
 }
 
-// Returns a custom block cursor character
+/// Return a custom block cursor character.
 pub fn get_block_cursor_glyph(height: i32, width: i32) -> RasterizedGlyph {
-    // Create a completely filled glyph
+    // Create a completely filled glyph.
     let buf = vec![255u8; (width * height * 3) as usize];
 
-    // Create a custom glyph with the rectangle data attached to it
+    // Create a custom glyph with the rectangle data attached to it.
     RasterizedGlyph { c: ' ', top: height, left: 0, height, width, buf: BitmapBuffer::RGB(buf) }
 }
diff --git a/alacritty/src/display.rs b/alacritty/src/display.rs
index aabd2631..f081e054 100644
--- a/alacritty/src/display.rs
+++ b/alacritty/src/display.rs
@@ -219,7 +219,7 @@ impl Display {
         // Update OpenGL projection.
         renderer.resize(&size_info);
 
-        // Call `clear` before showing the window, to make sure the surface is initialized.
+        // Clear screen.
         let background_color = config.colors.primary.background;
         renderer.with_api(&config, &size_info, |api| {
             api.clear(background_color);
@@ -244,7 +244,7 @@ impl Display {
 
         // Set window position.
         //
-        // TODO: replace `set_position` with `with_position` once available
+        // TODO: replace `set_position` with `with_position` once available.
         // Upstream issue: https://github.com/rust-windowing/winit/issues/806.
         if let Some(position) = config.window.position {
             window.set_outer_position(PhysicalPosition::from((position.x, position.y)));
diff --git a/alacritty/src/event.rs b/alacritty/src/event.rs
index 94c9a735..88d074bb 100644
--- a/alacritty/src/event.rs
+++ b/alacritty/src/event.rs
@@ -1,4 +1,4 @@
-//! Process window events
+//! Process window events.
 use std::borrow::Cow;
 use std::cmp::max;
 use std::env;
@@ -91,7 +91,7 @@ impl<'a, N: Notify + 'a, T: EventListener> input::ActionContext<T> for ActionCon
     fn scroll(&mut self, scroll: Scroll) {
         self.terminal.scroll_display(scroll);
 
-        // Update selection
+        // Update selection.
         if self.terminal.mode().contains(TermMode::VI)
             && self.terminal.selection().as_ref().map(|s| s.is_empty()) != Some(true)
         {
@@ -125,7 +125,7 @@ impl<'a, N: Notify + 'a, T: EventListener> input::ActionContext<T> for ActionCon
     fn update_selection(&mut self, point: Point, side: Side) {
         let point = self.terminal.visible_to_buffer(point);
 
-        // Update selection if one exists
+        // Update selection if one exists.
         let vi_mode = self.terminal.mode().contains(TermMode::VI);
         if let Some(selection) = self.terminal.selection_mut() {
             selection.update(point, side);
@@ -306,7 +306,7 @@ pub enum ClickState {
     TripleClick,
 }
 
-/// State of the mouse
+/// State of the mouse.
 #[derive(Debug)]
 pub struct Mouse {
     pub x: usize,
@@ -346,7 +346,7 @@ impl Default for Mouse {
     }
 }
 
-/// The event processor
+/// The event processor.
 ///
 /// Stores some state from received events and dispatches actions when they are
 /// triggered.
@@ -364,10 +364,9 @@ pub struct Processor<N> {
 }
 
 impl<N: Notify + OnResize> Processor<N> {
-    /// Create a new event processor
+    /// Create a new event processor.
     ///
-    /// Takes a writer which is expected to be hooked up to the write end of a
-    /// pty.
+    /// Takes a writer which is expected to be hooked up to the write end of a PTY.
     pub fn new(
         notifier: N,
         message_buffer: MessageBuffer,
@@ -528,11 +527,11 @@ impl<N: Notify + OnResize> Processor<N> {
             }
         });
 
-        // Write ref tests to disk
+        // Write ref tests to disk.
         self.write_ref_test_results(&terminal.lock());
     }
 
-    /// Handle events from glutin
+    /// Handle events from glutin.
     ///
     /// Doesn't take self mutably due to borrow checking.