Extend style guideline documentation

7 files changed, 93 insertions, 83 deletions

diff --git a/alacritty_terminal/src/config/colors.rs b/alacritty_terminal/src/config/colors.rs
index 5c057619..bae00ee1 100644
--- a/alacritty_terminal/src/config/colors.rs
+++ b/alacritty_terminal/src/config/colors.rs
@@ -59,7 +59,7 @@ where
                     index
                 );
 
-                // Return value out of range to ignore this color
+                // Return value out of range to ignore this color.
                 Ok(0)
             } else {
                 Ok(index)
@@ -68,7 +68,7 @@ where
         Err(err) => {
             error!(target: LOG_TARGET_CONFIG, "Problem with config: {}; ignoring setting", err);
 
-            // Return value out of range to ignore this color
+            // Return value out of range to ignore this color.
             Ok(0)
         },
     }
@@ -124,7 +124,7 @@ fn default_foreground() -> Rgb {
     Rgb { r: 0xea, g: 0xea, b: 0xea }
 }
 
-/// The 8-colors sections of config
+/// The 8-colors sections of config.
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct AnsiColors {
     #[serde(deserialize_with = "failure_default")]
diff --git a/alacritty_terminal/src/config/debug.rs b/alacritty_terminal/src/config/debug.rs
index f5ebe974..9c9d4fde 100644
--- a/alacritty_terminal/src/config/debug.rs
+++ b/alacritty_terminal/src/config/debug.rs
@@ -3,7 +3,7 @@ use serde::{Deserialize, Deserializer};
 
 use crate::config::{failure_default, LOG_TARGET_CONFIG};
 
-/// Debugging options
+/// Debugging options.
 #[serde(default)]
 #[derive(Deserialize, Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Debug {
@@ -13,15 +13,15 @@ pub struct Debug {
     #[serde(deserialize_with = "failure_default")]
     pub print_events: bool,
 
-    /// Keep the log file after quitting
+    /// Keep the log file after quitting.
     #[serde(deserialize_with = "failure_default")]
     pub persistent_logging: bool,
 
-    /// Should show render timer
+    /// Should show render timer.
     #[serde(deserialize_with = "failure_default")]
     pub render_timer: bool,
 
-    /// Record ref test
+    /// Record ref test.
     #[serde(skip)]
     pub ref_test: bool,
 }
diff --git a/alacritty_terminal/src/config/font.rs b/alacritty_terminal/src/config/font.rs
index a8a76c15..6a9120c9 100644
--- a/alacritty_terminal/src/config/font.rs
+++ b/alacritty_terminal/src/config/font.rs
@@ -9,7 +9,7 @@ use serde::{Deserialize, Deserializer};
 use crate::config::DefaultTrueBool;
 use crate::config::{failure_default, Delta, LOG_TARGET_CONFIG};
 
-/// Font config
+/// Font config.
 ///
 /// Defaults are provided at the level of this struct per platform, but not per
 /// field in this struct. It might be nice in the future to have defaults for
@@ -18,31 +18,31 @@ use crate::config::{failure_default, Delta, LOG_TARGET_CONFIG};
 #[serde(default)]
 #[derive(Debug, Deserialize, Clone, PartialEq, Eq)]
 pub struct Font {
-    /// Normal font face
+    /// Normal font face.
     #[serde(deserialize_with = "failure_default")]
     normal: FontDescription,
 
-    /// Bold font face
+    /// Bold font face.
     #[serde(deserialize_with = "failure_default")]
     bold: SecondaryFontDescription,
 
-    /// Italic font face
+    /// Italic font face.
     #[serde(deserialize_with = "failure_default")]
     italic: SecondaryFontDescription,
 
-    /// Bold italic font face
+    /// Bold italic font face.
     #[serde(deserialize_with = "failure_default")]
     bold_italic: SecondaryFontDescription,
 
-    /// Font size in points
+    /// Font size in points.
     #[serde(deserialize_with = "DeserializeSize::deserialize")]
     pub size: Size,
 
-    /// Extra spacing per character
+    /// Extra spacing per character.
     #[serde(deserialize_with = "failure_default")]
     pub offset: Delta<i8>,
 
-    /// Glyph offset within character cell
+    /// Glyph offset within character cell.
     #[serde(deserialize_with = "failure_default")]
     pub glyph_offset: Delta<i8>,
 
@@ -68,27 +68,27 @@ impl Default for Font {
 }
 
 impl Font {
-    /// Get a font clone with a size modification
+    /// Get a font clone with a size modification.
     pub fn with_size(self, size: Size) -> Font {
         Font { size, ..self }
     }
 
-    // Get normal font description
+    /// Get normal font description.
     pub fn normal(&self) -> &FontDescription {
         &self.normal
     }
 
-    // Get bold font description
+    /// Get bold font description.
     pub fn bold(&self) -> FontDescription {
         self.bold.desc(&self.normal)
     }
 
-    // Get italic font description
+    /// Get italic font description.
     pub fn italic(&self) -> FontDescription {
         self.italic.desc(&self.normal)
     }
 
-    // Get bold italic font description
+    /// Get bold italic font description.
     pub fn bold_italic(&self) -> FontDescription {
         self.bold_italic.desc(&self.normal)
     }
@@ -108,7 +108,7 @@ fn default_font_size() -> Size {
     Size::new(11.)
 }
 
-/// Description of the normal font
+/// Description of the normal font.
 #[serde(default)]
 #[derive(Debug, Deserialize, Clone, PartialEq, Eq)]
 pub struct FontDescription {
@@ -132,7 +132,7 @@ impl Default for FontDescription {
     }
 }
 
-/// Description of the italic and bold font
+/// Description of the italic and bold font.
 #[serde(default)]
 #[derive(Debug, Default, Deserialize, Clone, PartialEq, Eq)]
 pub struct SecondaryFontDescription {
@@ -198,7 +198,7 @@ impl DeserializeSize for Size {
             .deserialize_any(NumVisitor::<D> { _marker: PhantomData })
             .map(|v| Size::new(v as _));
 
-        // Use default font size as fallback
+        // Use default font size as fallback.
         match size {
             Ok(size) => Ok(size),
             Err(err) => {
diff --git a/alacritty_terminal/src/config/mod.rs b/alacritty_terminal/src/config/mod.rs
index 53aae91a..de72d3e2 100644
--- a/alacritty_terminal/src/config/mod.rs
+++ b/alacritty_terminal/src/config/mod.rs
@@ -44,68 +44,68 @@ const DEFAULT_CURSOR_THICKNESS: f32 = 0.15;
 
 pub type MockConfig = Config<HashMap<String, serde_yaml::Value>>;
 
-/// Top-level config type
+/// Top-level config type.
 #[derive(Debug, PartialEq, Default, Deserialize)]
 pub struct Config<T> {
-    /// Pixel padding
+    /// Pixel padding.
     #[serde(default, deserialize_with = "failure_default")]
     pub padding: Option<Delta<u8>>,
 
-    /// TERM env variable
+    /// TERM env variable.
     #[serde(default, deserialize_with = "failure_default")]
     pub env: HashMap<String, String>,
 
-    /// Font configuration
+    /// Font configuration.
     #[serde(default, deserialize_with = "failure_default")]
     pub font: Font,
 
-    /// Should draw bold text with brighter colors instead of bold font
+    /// Should draw bold text with brighter colors instead of bold font.
     #[serde(default, deserialize_with = "failure_default")]
     draw_bold_text_with_bright_colors: bool,
 
     #[serde(default, deserialize_with = "failure_default")]
     pub colors: Colors,
 
-    /// Background opacity from 0.0 to 1.0
+    /// Background opacity from 0.0 to 1.0.
     #[serde(default, deserialize_with = "failure_default")]
     background_opacity: Percentage,
 
-    /// Window configuration
+    /// Window configuration.
     #[serde(default, deserialize_with = "failure_default")]
     pub window: WindowConfig,
 
     #[serde(default, deserialize_with = "failure_default")]
     pub selection: Selection,
 
-    /// Path to a shell program to run on startup
+    /// Path to a shell program to run on startup.
     #[serde(default, deserialize_with = "from_string_or_deserialize")]
     pub shell: Option<Shell<'static>>,
 
-    /// Path where config was loaded from
+    /// Path where config was loaded from.
     #[serde(default, deserialize_with = "failure_default")]
     pub config_path: Option<PathBuf>,
 
-    /// Visual bell configuration
+    /// Visual bell configuration.
     #[serde(default, deserialize_with = "failure_default")]
     pub visual_bell: VisualBellConfig,
 
-    /// Use dynamic title
+    /// Use dynamic title.
     #[serde(default, deserialize_with = "failure_default")]
     dynamic_title: DefaultTrueBool,
 
-    /// Live config reload
+    /// Live config reload.
     #[serde(default, deserialize_with = "failure_default")]
     live_config_reload: DefaultTrueBool,
 
-    /// How much scrolling history to keep
+    /// How much scrolling history to keep.
     #[serde(default, deserialize_with = "failure_default")]
     pub scrolling: Scrolling,
 
-    /// Cursor configuration
+    /// Cursor configuration.
     #[serde(default, deserialize_with = "failure_default")]
     pub cursor: Cursor,
 
-    /// Use WinPTY backend even if ConPTY is available
+    /// Use WinPTY backend even if ConPTY is available.
     #[cfg(windows)]
     #[serde(default, deserialize_with = "failure_default")]
     pub winpty_backend: bool,
@@ -114,19 +114,19 @@ pub struct Config<T> {
     #[serde(default, deserialize_with = "failure_default")]
     alt_send_esc: DefaultTrueBool,
 
-    /// Shell startup directory
+    /// Shell startup directory.
     #[serde(default, deserialize_with = "option_explicit_none")]
     pub working_directory: Option<PathBuf>,
 
-    /// Debug options
+    /// Debug options.
     #[serde(default, deserialize_with = "failure_default")]
     pub debug: Debug,
 
-    /// Additional configuration options not directly required by the terminal
+    /// Additional configuration options not directly required by the terminal.
     #[serde(flatten)]
     pub ui_config: T,
 
-    /// Remain open after child process exits
+    /// Remain open after child process exits.
     #[serde(skip)]
     pub hold: bool,
 
@@ -149,13 +149,13 @@ impl<T> Config<T> {
         self.draw_bold_text_with_bright_colors
     }
 
-    /// Should show render timer
+    /// Should show render timer.
     #[inline]
     pub fn render_timer(&self) -> bool {
         self.render_timer.unwrap_or(self.debug.render_timer)
     }
 
-    /// Live config reload
+    /// Live config reload.
     #[inline]
     pub fn live_config_reload(&self) -> bool {
         self.live_config_reload.0
@@ -200,13 +200,13 @@ impl<T> Config<T> {
         self.dynamic_title.0 = dynamic_title;
     }
 
-    /// Send escape sequences using the alt key
+    /// Send escape sequences using the alt key.
     #[inline]
     pub fn alt_send_esc(&self) -> bool {
         self.alt_send_esc.0
     }
 
-    /// Keep the log file after quitting Alacritty
+    /// Keep the log file after quitting Alacritty.
     #[inline]
     pub fn persistent_logging(&self) -> bool {
         self.persistent_logging.unwrap_or(self.debug.persistent_logging)
@@ -316,14 +316,14 @@ impl FromString for Option<Shell<'_>> {
     }
 }
 
-/// A delta for a point in a 2 dimensional plane
+/// A delta for a point in a 2 dimensional plane.
 #[serde(default, bound(deserialize = "T: Deserialize<'de> + Default"))]
 #[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Eq)]
 pub struct Delta<T: Default + PartialEq + Eq> {
-    /// Horizontal change
+    /// Horizontal change.
     #[serde(deserialize_with = "failure_default")]
     pub x: T,
-    /// Vertical change
+    /// Vertical change.
     #[serde(deserialize_with = "failure_default")]
     pub y: T,
 }
@@ -407,7 +407,7 @@ where
     })
 }
 
-// Used over From<String>, to allow implementation for foreign types
+// Used over From<String>, to allow implementation for foreign types.
 pub trait FromString {
     fn from(input: String) -> Self;
 }
diff --git a/alacritty_terminal/src/config/scrolling.rs b/alacritty_terminal/src/config/scrolling.rs
index 899ca1b3..136e9389 100644
--- a/alacritty_terminal/src/config/scrolling.rs
+++ b/alacritty_terminal/src/config/scrolling.rs
@@ -3,7 +3,7 @@ use serde::{Deserialize, Deserializer};
 
 use crate::config::{failure_default, LOG_TARGET_CONFIG, MAX_SCROLLBACK_LINES};
 
-/// Struct for scrolling related settings
+/// Struct for scrolling related settings.
 #[serde(default)]
 #[derive(Deserialize, Copy, Clone, Default, Debug, PartialEq, Eq)]
 pub struct Scrolling {
@@ -34,7 +34,7 @@ impl Scrolling {
         self.faux_multiplier.map(|sm| sm.0)
     }
 
-    // Update the history size, used in ref tests
+    // Update the history size, used in ref tests.
     pub fn set_history(&mut self, history: u32) {
         self.history = ScrollingHistory(history);
     }
diff --git a/alacritty_terminal/src/config/visual_bell.rs b/alacritty_terminal/src/config/visual_bell.rs
index 8981c929..1a0a327b 100644
--- a/alacritty_terminal/src/config/visual_bell.rs
+++ b/alacritty_terminal/src/config/visual_bell.rs
@@ -8,15 +8,15 @@ use crate::term::color::Rgb;
 #[serde(default)]
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct VisualBellConfig {
-    /// Visual bell animation function
+    /// Visual bell animation function.
     #[serde(deserialize_with = "failure_default")]
     pub animation: VisualBellAnimation,
 
-    /// Visual bell duration in milliseconds
+    /// Visual bell duration in milliseconds.
     #[serde(deserialize_with = "failure_default")]
     pub duration: u16,
 
-    /// Visual bell flash color
+    /// Visual bell flash color.
     #[serde(deserialize_with = "failure_default")]
     pub color: Rgb,
 }
@@ -32,7 +32,7 @@ impl Default for VisualBellConfig {
 }
 
 impl VisualBellConfig {
-    /// Visual bell duration in milliseconds
+    /// Visual bell duration in milliseconds.
     #[inline]
     pub fn duration(&self) -> Duration {
         Duration::from_millis(u64::from(self.duration))
@@ -43,15 +43,25 @@ impl VisualBellConfig {
 /// Penner's Easing Functions.
 #[derive(Clone, Copy, Debug, Deserialize, PartialEq, Eq)]
 pub enum VisualBellAnimation {
-    Ease,         // CSS
-    EaseOut,      // CSS
-    EaseOutSine,  // Penner
-    EaseOutQuad,  // Penner
-    EaseOutCubic, // Penner
-    EaseOutQuart, // Penner
-    EaseOutQuint, // Penner
-    EaseOutExpo,  // Penner
-    EaseOutCirc,  // Penner
+    // CSS animation.
+    Ease,
+    // CSS animation.
+    EaseOut,
+    // Penner animation.
+    EaseOutSine,
+    // Penner animation.
+    EaseOutQuad,
+    // Penner animation.
+    EaseOutCubic,
+    // Penner animation.
+    EaseOutQuart,
+    // Penner animation.
+    EaseOutQuint,
+    // Penner animation.
+    EaseOutExpo,
+    // Penner animation.
+    EaseOutCirc,
+    // Penner animation.
     Linear,
 }
 
diff --git a/alacritty_terminal/src/config/window.rs b/alacritty_terminal/src/config/window.rs
index 9b86ba8a..5e934f6f 100644
--- a/alacritty_terminal/src/config/window.rs
+++ b/alacritty_terminal/src/config/window.rs
@@ -13,47 +13,47 @@ pub const DEFAULT_NAME: &str = "Alacritty";
 #[serde(default)]
 #[derive(Deserialize, Debug, Clone, PartialEq, Eq)]
 pub struct WindowConfig {
-    /// Initial dimensions
+    /// Initial dimensions.
     #[serde(deserialize_with = "failure_default")]
     pub dimensions: Dimensions,
 
-    /// Initial position
+    /// Initial position.
     #[serde(deserialize_with = "failure_default")]
     pub position: Option<Delta<i32>>,
 
-    /// Pixel padding
+    /// Pixel padding.
     #[serde(deserialize_with = "failure_default")]
     pub padding: Delta<u8>,
 
-    /// Draw the window with title bar / borders
+    /// Draw the window with title bar / borders.
     #[serde(deserialize_with = "failure_default")]
     pub decorations: Decorations,
 
-    /// Spread out additional padding evenly
+    /// Spread out additional padding evenly.
     #[serde(deserialize_with = "failure_default")]
     pub dynamic_padding: bool,
 
-    /// Startup mode
+    /// Startup mode.
     #[serde(deserialize_with = "failure_default")]
     startup_mode: StartupMode,
 
-    /// Window title
+    /// Window title.
     #[serde(default = "default_title")]
     pub title: String,
 
-    /// Window class
+    /// Window class.
     #[serde(deserialize_with = "from_string_or_deserialize")]
     pub class: Class,
 
-    /// XEmbed parent
+    /// XEmbed parent.
     #[serde(skip)]
     pub embed: Option<c_ulong>,
 
-    /// GTK theme variant
+    /// GTK theme variant.
     #[serde(deserialize_with = "option_explicit_none")]
     pub gtk_theme_variant: Option<String>,
 
-    /// TODO: DEPRECATED
+    // TODO: DEPRECATED
     #[serde(deserialize_with = "failure_default")]
     pub start_maximized: Option<bool>,
 }
@@ -124,17 +124,17 @@ impl Default for Decorations {
     }
 }
 
-/// Window Dimensions
+/// Window Dimensions.
 ///
-/// Newtype to avoid passing values incorrectly
+/// Newtype to avoid passing values incorrectly.
 #[serde(default)]
 #[derive(Default, Debug, Copy, Clone, Deserialize, PartialEq, Eq)]
 pub struct Dimensions {
-    /// Window width in character columns
+    /// Window width in character columns.
     #[serde(deserialize_with = "failure_default")]
     columns: Column,
 
-    /// Window Height in character lines
+    /// Window Height in character lines.
     #[serde(deserialize_with = "failure_default")]
     lines: Line,
 }
@@ -144,20 +144,20 @@ impl Dimensions {
         Dimensions { columns, lines }
     }
 
-    /// Get lines
+    /// Get lines.
     #[inline]
     pub fn lines_u32(&self) -> u32 {
         self.lines.0 as u32
     }
 
-    /// Get columns
+    /// Get columns.
     #[inline]
     pub fn columns_u32(&self) -> u32 {
         self.columns.0 as u32
     }
 }
 
-/// Window class hint
+/// Window class hint.
 #[serde(default)]
 #[derive(Deserialize, Debug, Clone, PartialEq, Eq)]
 pub struct Class {