diff options
author | Christian Duerr <contact@christianduerr.com> | 2020-05-05 22:50:23 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-05-05 22:50:23 +0000 |
commit | 81ce93574f62d4b117fdd79af65391f30316a457 (patch) | |
tree | 951a0578860c6028e2dfff0ca83879001c6b2385 | |
parent | 04f0bcaf54ed373128ca0f84ee8fcdd8e52bce23 (diff) |
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. |