Unnamed repository; edit this file 'description' to name the repository.
Add docs to helix-stdx, helix-tui, helix-vcs (#13765)
| -rw-r--r-- | helix-stdx/src/env.rs | 11 | ||||
| -rw-r--r-- | helix-stdx/src/faccess.rs | 1 | ||||
| -rw-r--r-- | helix-stdx/src/lib.rs | 3 | ||||
| -rw-r--r-- | helix-stdx/src/path.rs | 3 | ||||
| -rw-r--r-- | helix-stdx/src/range.rs | 3 | ||||
| -rw-r--r-- | helix-stdx/src/rope.rs | 2 | ||||
| -rw-r--r-- | helix-tui/src/backend/crossterm.rs | 1 | ||||
| -rw-r--r-- | helix-tui/src/backend/mod.rs | 15 | ||||
| -rw-r--r-- | helix-tui/src/buffer.rs | 17 | ||||
| -rw-r--r-- | helix-tui/src/layout.rs | 12 | ||||
| -rw-r--r-- | helix-tui/src/symbols.rs | 2 | ||||
| -rw-r--r-- | helix-tui/src/terminal.rs | 6 | ||||
| -rw-r--r-- | helix-tui/src/widgets/table.rs | 1 | ||||
| -rw-r--r-- | helix-vcs/Cargo.toml | 2 | ||||
| -rw-r--r-- | helix-vcs/src/diff.rs | 9 | ||||
| -rw-r--r-- | helix-vcs/src/lib.rs | 12 | ||||
| -rw-r--r-- | helix-vcs/src/status.rs | 22 |
17 files changed, 102 insertions, 20 deletions
diff --git a/helix-stdx/src/env.rs b/helix-stdx/src/env.rs index b3f46c25..6f9a091e 100644 --- a/helix-stdx/src/env.rs +++ b/helix-stdx/src/env.rs @@ -1,3 +1,4 @@ +//! Functions for working with the host environment. use std::{ borrow::Cow, ffi::{OsStr, OsString}, @@ -10,9 +11,9 @@ use once_cell::sync::Lazy; // We keep the CWD as a static so that we can access it in places where we don't have access to the Editor static CWD: RwLock<Option<PathBuf>> = RwLock::new(None); -// Get the current working directory. -// This information is managed internally as the call to std::env::current_dir -// might fail if the cwd has been deleted. +/// Get the current working directory. +/// This information is managed internally as the call to std::env::current_dir +/// might fail if the cwd has been deleted. pub fn current_working_dir() -> PathBuf { if let Some(path) = &*CWD.read().unwrap() { return path.clone(); @@ -37,6 +38,7 @@ pub fn current_working_dir() -> PathBuf { cwd } +/// Update the current working directory. pub fn set_current_working_dir(path: impl AsRef<Path>) -> std::io::Result<Option<PathBuf>> { let path = crate::path::canonicalize(path); std::env::set_current_dir(&path)?; @@ -45,14 +47,17 @@ pub fn set_current_working_dir(path: impl AsRef<Path>) -> std::io::Result<Option Ok(cwd.replace(path)) } +/// Checks if the given environment variable is set. pub fn env_var_is_set(env_var_name: &str) -> bool { std::env::var_os(env_var_name).is_some() } +/// Checks if a binary with the given name exists. pub fn binary_exists<T: AsRef<OsStr>>(binary_name: T) -> bool { which::which(binary_name).is_ok() } +/// Attempts to find a binary of the given name. See [which](https://linux.die.net/man/1/which). pub fn which<T: AsRef<OsStr>>( binary_name: T, ) -> Result<std::path::PathBuf, ExecutableNotFoundError> { diff --git a/helix-stdx/src/faccess.rs b/helix-stdx/src/faccess.rs index 80b668b1..a69ad3f4 100644 --- a/helix-stdx/src/faccess.rs +++ b/helix-stdx/src/faccess.rs @@ -1,3 +1,4 @@ +//! Functions for managine file metadata. //! From <https://github.com/Freaky/faccess> use std::io; diff --git a/helix-stdx/src/lib.rs b/helix-stdx/src/lib.rs index d09df587..e371f392 100644 --- a/helix-stdx/src/lib.rs +++ b/helix-stdx/src/lib.rs @@ -1,3 +1,6 @@ +//! Extensions to the standard library. A collection of helper functions +//! used throughout helix. + pub mod env; pub mod faccess; pub mod path; diff --git a/helix-stdx/src/path.rs b/helix-stdx/src/path.rs index 53081b0f..740f7bcb 100644 --- a/helix-stdx/src/path.rs +++ b/helix-stdx/src/path.rs @@ -1,3 +1,5 @@ +//! Functions for working with [Path]. + pub use etcetera::home_dir; use once_cell::sync::Lazy; use regex_cursor::{engines::meta::Regex, Input}; @@ -140,6 +142,7 @@ pub fn canonicalize(path: impl AsRef<Path>) -> PathBuf { normalize(path) } +/// Convert path into a relative path pub fn get_relative_path<'a, P>(path: P) -> Cow<'a, Path> where P: Into<Cow<'a, Path>>, diff --git a/helix-stdx/src/range.rs b/helix-stdx/src/range.rs index 0b241199..dcf7bfc2 100644 --- a/helix-stdx/src/range.rs +++ b/helix-stdx/src/range.rs @@ -1,3 +1,5 @@ +//! Provides [Range] type expanding on [RangeBounds]. + use std::ops::{self, RangeBounds}; /// A range of `char`s within the text. @@ -66,6 +68,7 @@ pub fn is_subset<const ALLOW_EMPTY: bool>( } } +/// Similar to is_subset but requires each element of `super_set` to be matched pub fn is_exact_subset( mut super_set: impl Iterator<Item = Range>, mut sub_set: impl Iterator<Item = Range>, diff --git a/helix-stdx/src/rope.rs b/helix-stdx/src/rope.rs index 996fee31..1ba4bc53 100644 --- a/helix-stdx/src/rope.rs +++ b/helix-stdx/src/rope.rs @@ -1,3 +1,4 @@ +//! Functions and types for working with [RopeSlice] use std::fmt; use std::ops::{Bound, RangeBounds}; @@ -8,6 +9,7 @@ use ropey::iter::Chunks; use ropey::RopeSlice; use unicode_segmentation::{GraphemeCursor, GraphemeIncomplete}; +/// Additional utility functions for [RopeSlice] pub trait RopeSliceExt<'a>: Sized { fn ends_with(self, text: &str) -> bool; fn starts_with(self, text: &str) -> bool; diff --git a/helix-tui/src/backend/crossterm.rs b/helix-tui/src/backend/crossterm.rs index e8947ee0..28e20419 100644 --- a/helix-tui/src/backend/crossterm.rs +++ b/helix-tui/src/backend/crossterm.rs @@ -95,6 +95,7 @@ impl Capabilities { } } +/// Terminal backend supporting a wide variety of terminals pub struct CrosstermBackend<W: Write> { buffer: W, capabilities: Capabilities, diff --git a/helix-tui/src/backend/mod.rs b/helix-tui/src/backend/mod.rs index 6994bc6f..d8b0555c 100644 --- a/helix-tui/src/backend/mod.rs +++ b/helix-tui/src/backend/mod.rs @@ -1,3 +1,5 @@ +//! Provides interface for controlling the terminal + use std::io; use crate::{buffer::Cell, terminal::Config}; @@ -12,19 +14,32 @@ pub use self::crossterm::CrosstermBackend; mod test; pub use self::test::TestBackend; +/// Representation of a terminal backend. pub trait Backend { + /// Claims the terminal for TUI use. fn claim(&mut self, config: Config) -> Result<(), io::Error>; + /// Update terminal configuration. fn reconfigure(&mut self, config: Config) -> Result<(), io::Error>; + /// Restores the terminal to a normal state, undoes `claim` fn restore(&mut self, config: Config) -> Result<(), io::Error>; + /// Forcibly resets the terminal, ignoring errors and configuration fn force_restore() -> Result<(), io::Error>; + /// Draws styled text to the terminal fn draw<'a, I>(&mut self, content: I) -> Result<(), io::Error> where I: Iterator<Item = (u16, u16, &'a Cell)>; + /// Hides the cursor fn hide_cursor(&mut self) -> Result<(), io::Error>; + /// Sets the cursor to the given shape fn show_cursor(&mut self, kind: CursorKind) -> Result<(), io::Error>; + /// Gets the current position of the cursor fn get_cursor(&mut self) -> Result<(u16, u16), io::Error>; + /// Sets the cursor to the given position fn set_cursor(&mut self, x: u16, y: u16) -> Result<(), io::Error>; + /// Clears the terminal fn clear(&mut self) -> Result<(), io::Error>; + /// Gets the size of the terminal in cells fn size(&self) -> Result<Rect, io::Error>; + /// Flushes the terminal buffer fn flush(&mut self) -> Result<(), io::Error>; } diff --git a/helix-tui/src/buffer.rs b/helix-tui/src/buffer.rs index 2cd30324..4f57e8e5 100644 --- a/helix-tui/src/buffer.rs +++ b/helix-tui/src/buffer.rs @@ -1,3 +1,4 @@ +//! Contents of a terminal screen. A [Buffer] is made up of [Cell]s. use crate::text::{Span, Spans}; use helix_core::unicode::width::UnicodeWidthStr; use std::cmp::min; @@ -5,7 +6,7 @@ use unicode_segmentation::UnicodeSegmentation; use helix_view::graphics::{Color, Modifier, Rect, Style, UnderlineStyle}; -/// A buffer cell +/// One cell of the terminal. Contains one stylized grapheme. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Cell { pub symbol: String, @@ -17,28 +18,33 @@ pub struct Cell { } impl Cell { + /// Set the cell's grapheme pub fn set_symbol(&mut self, symbol: &str) -> &mut Cell { self.symbol.clear(); self.symbol.push_str(symbol); self } + /// Set the cell's grapheme to a [char] pub fn set_char(&mut self, ch: char) -> &mut Cell { self.symbol.clear(); self.symbol.push(ch); self } + /// Set the foreground [Color] pub fn set_fg(&mut self, color: Color) -> &mut Cell { self.fg = color; self } + /// Set the background [Color] pub fn set_bg(&mut self, color: Color) -> &mut Cell { self.bg = color; self } + /// Set the [Style] of the cell pub fn set_style(&mut self, style: Style) -> &mut Cell { if let Some(c) = style.fg { self.fg = c; @@ -58,6 +64,7 @@ impl Cell { self } + /// Returns the current style of the cell pub fn style(&self) -> Style { Style::default() .fg(self.fg) @@ -67,6 +74,7 @@ impl Cell { .add_modifier(self.modifier) } + /// Resets the cell to a default blank state pub fn reset(&mut self) { self.symbol.clear(); self.symbol.push(' '); @@ -495,6 +503,8 @@ impl Buffer { (x_offset as u16, y) } + /// Print at most the first `width` characters of a [Spans] if enough space is available + /// until the end of the line. Appends a `…` at the end of truncated lines. pub fn set_spans_truncated(&mut self, x: u16, y: u16, spans: &Spans, width: u16) -> (u16, u16) { // prevent panic if out of range if !self.in_bounds(x, y) || width == 0 { @@ -536,6 +546,8 @@ impl Buffer { (x_offset as u16, y) } + /// Print at most the first `width` characters of a [Spans] if enough space is available + /// until the end of the line pub fn set_spans(&mut self, x: u16, y: u16, spans: &Spans, width: u16) -> (u16, u16) { let mut remaining_width = width; let mut x = x; @@ -557,6 +569,8 @@ impl Buffer { (x, y) } + /// Print at most the first `width` characters of a [Span] if enough space is available + /// until the end of the line pub fn set_span(&mut self, x: u16, y: u16, span: &Span, width: u16) -> (u16, u16) { self.set_stringn(x, y, span.content.as_ref(), width as usize, span.style) } @@ -573,6 +587,7 @@ impl Buffer { } } + /// Set all cells in the [area](Rect) to the given [Style] pub fn set_style(&mut self, area: Rect, style: Style) { for y in area.top()..area.bottom() { for x in area.left()..area.right() { diff --git a/helix-tui/src/layout.rs b/helix-tui/src/layout.rs index 50a16415..83edc615 100644 --- a/helix-tui/src/layout.rs +++ b/helix-tui/src/layout.rs @@ -1,3 +1,5 @@ +//! Layout engine for terminal + use std::cell::RefCell; use std::collections::HashMap; @@ -7,6 +9,7 @@ use cassowary::{Constraint as CassowaryConstraint, Expression, Solver, Variable} use helix_view::graphics::{Margin, Rect}; +/// Enum of all corners #[derive(Debug, Hash, Clone, Copy, PartialEq, Eq)] pub enum Corner { TopLeft, @@ -15,12 +18,14 @@ pub enum Corner { BottomLeft, } +/// Direction a [Rect] should be split #[derive(Debug, Hash, Clone, PartialEq, Eq)] pub enum Direction { Horizontal, Vertical, } +/// Describes requirements of a [Rect] to be split #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Constraint { // TODO: enforce range 0 - 100 @@ -46,6 +51,7 @@ impl Constraint { } } +/// How content should be aligned #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Alignment { Left, @@ -53,6 +59,7 @@ pub enum Alignment { Right, } +/// Description of a how a [Rect] should be split #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct Layout { direction: Direction, @@ -75,6 +82,7 @@ impl Default for Layout { } impl Layout { + /// Returns a layout with the given [Constraint]s. pub fn constraints<C>(mut self, constraints: C) -> Layout where C: Into<Vec<Constraint>>, @@ -83,21 +91,25 @@ impl Layout { self } + /// Returns a layout wit the given margins on all sides. pub const fn margin(mut self, margin: u16) -> Layout { self.margin = Margin::all(margin); self } + /// Returns a layout with the given horizontal margins. pub const fn horizontal_margin(mut self, horizontal: u16) -> Layout { self.margin.horizontal = horizontal; self } + /// Returns a layout with the given vertical margins. pub const fn vertical_margin(mut self, vertical: u16) -> Layout { self.margin.vertical = vertical; self } + /// Returns a layout with the given [Direction]. pub const fn direction(mut self, direction: Direction) -> Layout { self.direction = direction; self diff --git a/helix-tui/src/symbols.rs b/helix-tui/src/symbols.rs index 040e77f6..118354df 100644 --- a/helix-tui/src/symbols.rs +++ b/helix-tui/src/symbols.rs @@ -1,3 +1,5 @@ +//! Common TUI symbols including blocks, bars, braille, lines + pub mod block { pub const FULL: &str = "█"; pub const SEVEN_EIGHTHS: &str = "▉"; diff --git a/helix-tui/src/terminal.rs b/helix-tui/src/terminal.rs index d2a911cf..969b285c 100644 --- a/helix-tui/src/terminal.rs +++ b/helix-tui/src/terminal.rs @@ -1,3 +1,6 @@ +//! Terminal interface provided through the [Terminal] type. +//! Frontend for [Backend] + use crate::{backend::Backend, buffer::Buffer}; use helix_view::editor::Config as EditorConfig; use helix_view::graphics::{CursorKind, Rect}; @@ -17,6 +20,7 @@ pub struct Viewport { resize_behavior: ResizeBehavior, } +/// Terminal configuration #[derive(Debug)] pub struct Config { pub enable_mouse_capture: bool, @@ -47,7 +51,7 @@ pub struct TerminalOptions { pub viewport: Viewport, } -/// Interface to the terminal backed by Termion +/// Interface to the terminal backed by crossterm #[derive(Debug)] pub struct Terminal<B> where diff --git a/helix-tui/src/widgets/table.rs b/helix-tui/src/widgets/table.rs index 9c67a376..234df2e4 100644 --- a/helix-tui/src/widgets/table.rs +++ b/helix-tui/src/widgets/table.rs @@ -331,6 +331,7 @@ impl<'a> Table<'a> { } } +/// Track [Table] scroll offset and selection #[derive(Debug, Default, Clone)] pub struct TableState { pub offset: usize, diff --git a/helix-vcs/Cargo.toml b/helix-vcs/Cargo.toml index d8936686..7ed11982 100644 --- a/helix-vcs/Cargo.toml +++ b/helix-vcs/Cargo.toml @@ -9,8 +9,6 @@ categories.workspace = true repository.workspace = true homepage.workspace = true -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html - [dependencies] helix-core = { path = "../helix-core" } helix-event = { path = "../helix-event" } diff --git a/helix-vcs/src/diff.rs b/helix-vcs/src/diff.rs index 6ec29813..cc97ef85 100644 --- a/helix-vcs/src/diff.rs +++ b/helix-vcs/src/diff.rs @@ -35,6 +35,7 @@ struct DiffInner { hunks: Vec<Hunk>, } +/// Representation of a diff that can be updated. #[derive(Clone, Debug)] pub struct DiffHandle { channel: UnboundedSender<Event>, @@ -65,10 +66,12 @@ impl DiffHandle { (differ, handle) } + /// Switch base and modified texts' roles pub fn invert(&mut self) { self.inverted = !self.inverted; } + /// Load the actual diff pub fn load(&self) -> Diff { Diff { diff: self.diff.read(), @@ -89,6 +92,7 @@ impl DiffHandle { self.update_document_impl(doc, self.inverted, Some(RenderLock { lock, timeout })) } + /// Updates the base text of the diff. Returns if the update was successful. pub fn update_diff_base(&self, diff_base: Rope) -> bool { self.update_document_impl(diff_base, !self.inverted, None) } @@ -128,6 +132,7 @@ pub struct Diff<'a> { } impl Diff<'_> { + /// Returns the base [Rope] of the [Diff] pub fn diff_base(&self) -> &Rope { if self.inverted { &self.diff.doc @@ -136,6 +141,7 @@ impl Diff<'_> { } } + /// Returns the [Rope] being compared against pub fn doc(&self) -> &Rope { if self.inverted { &self.diff.diff_base @@ -166,6 +172,7 @@ impl Diff<'_> { self.len() == 0 } + /// Gives the index of the first hunk after the given line, if one exists. pub fn next_hunk(&self, line: u32) -> Option<u32> { let hunk_range = if self.inverted { |hunk: &Hunk| hunk.before.clone() @@ -192,6 +199,7 @@ impl Diff<'_> { } } + /// Gives the index of the first hunk before the given line, if one exists. pub fn prev_hunk(&self, line: u32) -> Option<u32> { let hunk_range = if self.inverted { |hunk: &Hunk| hunk.before.clone() @@ -235,6 +243,7 @@ impl Diff<'_> { } } + /// Returns the index of the hunk containing the given line if it exists. pub fn hunk_at(&self, line: u32, include_removal: bool) -> Option<u32> { let hunk_range = if self.inverted { |hunk: &Hunk| hunk.before.clone() diff --git a/helix-vcs/src/lib.rs b/helix-vcs/src/lib.rs index 539be779..4c5f2036 100644 --- a/helix-vcs/src/lib.rs +++ b/helix-vcs/src/lib.rs @@ -1,3 +1,7 @@ +//! `helix_vcs` provides types for working with diffs from a Version Control System (VCS). +//! Currently `git` is the only supported provider for diffs, but this architecture allows +//! for other providers to be added in the future. + use anyhow::{anyhow, bail, Result}; use arc_swap::ArcSwap; use std::{ @@ -16,12 +20,16 @@ mod status; pub use status::FileChange; +/// Contains all active diff providers. Diff providers are compiled in via features. Currently +/// only `git` is supported. #[derive(Clone)] pub struct DiffProviderRegistry { providers: Vec<DiffProvider>, } impl DiffProviderRegistry { + /// Get the given file from the VCS. This provides the unedited document as a "base" + /// for a diff to be created. pub fn get_diff_base(&self, file: &Path) -> Option<Vec<u8>> { self.providers .iter() @@ -35,6 +43,7 @@ impl DiffProviderRegistry { }) } + /// Get the current name of the current [HEAD](https://stackoverflow.com/questions/2304087/what-is-head-in-git). pub fn get_current_head_name(&self, file: &Path) -> Option<Arc<ArcSwap<Box<str>>>> { self.providers .iter() @@ -75,6 +84,7 @@ impl Default for DiffProviderRegistry { let providers = vec![ #[cfg(feature = "git")] DiffProvider::Git, + DiffProvider::None, ]; DiffProviderRegistry { providers } } @@ -85,7 +95,7 @@ impl Default for DiffProviderRegistry { /// /// `Copy` is simply to ensure the `clone()` call is the simplest it can be. #[derive(Copy, Clone)] -pub enum DiffProvider { +enum DiffProvider { #[cfg(feature = "git")] Git, None, diff --git a/helix-vcs/src/status.rs b/helix-vcs/src/status.rs index f3433490..0240cad1 100644 --- a/helix-vcs/src/status.rs +++ b/helix-vcs/src/status.rs @@ -1,18 +1,16 @@ use std::path::{Path, PathBuf}; +/// States for a file having been changed. pub enum FileChange { - Untracked { - path: PathBuf, - }, - Modified { - path: PathBuf, - }, - Conflict { - path: PathBuf, - }, - Deleted { - path: PathBuf, - }, + /// Not tracked by the VCS. + Untracked { path: PathBuf }, + /// File has been modified. + Modified { path: PathBuf }, + /// File modification is in conflict with a different update. + Conflict { path: PathBuf }, + /// File has been deleted. + Deleted { path: PathBuf }, + /// File has been renamed. Renamed { from_path: PathBuf, to_path: PathBuf, |