From 4652d4313466803e40b537b21ed87fe896f16318 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 20 Jan 2022 10:07:29 +0100 Subject: [PATCH 1/9] doc: Use imperative mode for doc comments in term.rs. This is consistent with e.g. PEP-257. Before, the doc comments were inconsistent on this matter. --- src/term.rs | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/src/term.rs b/src/term.rs index 56287dcb..128749b8 100644 --- a/src/term.rs +++ b/src/term.rs @@ -60,13 +60,13 @@ pub enum TermFamily { pub struct TermFeatures<'a>(&'a Term); impl<'a> TermFeatures<'a> { - /// Checks if this is a real user attended terminal (`isatty`) + /// Check if this is a real user attended terminal (`isatty`) #[inline] pub fn is_attended(&self) -> bool { is_a_terminal(self.0) } - /// Checks if colors are supported by this terminal. + /// Check if colors are supported by this terminal. /// /// This does not check if colors are enabled. Currently all terminals /// are considered to support colors @@ -75,7 +75,7 @@ impl<'a> TermFeatures<'a> { is_a_color_terminal(self.0) } - /// Checks if this terminal is an msys terminal. + /// Check if this terminal is an msys terminal. /// /// This is sometimes useful to disable features that are known to not /// work on msys terminals or require special handling. @@ -91,13 +91,13 @@ impl<'a> TermFeatures<'a> { } } - /// Checks if this terminal wants emojis. + /// Check if this terminal wants emojis. #[inline] pub fn wants_emoji(&self) -> bool { self.is_attended() && wants_emoji() } - /// Returns the family of the terminal. + /// Return the family of the terminal. #[inline] pub fn family(&self) -> TermFamily { if !self.is_attended() { @@ -203,7 +203,7 @@ impl Term { }) } - /// Returns the style for the term + /// Return the style for the term #[inline] pub fn style(&self) -> Style { match self.inner.target { @@ -214,7 +214,7 @@ impl Term { } } - /// Returns the target + /// Return the target #[inline] pub fn target(&self) -> TermTarget { self.inner.target.clone() @@ -228,7 +228,7 @@ impl Term { } } - /// Writes a string to the terminal and adds a newline. + /// Write a string to the terminal and add a newline. pub fn write_line(&self, s: &str) -> io::Result<()> { match self.inner.buffer { Some(ref mutex) => { @@ -241,7 +241,7 @@ impl Term { } } - /// Read a single character from the terminal + /// Read a single character from the terminal. /// /// This does not echo the character and blocks until a single character /// is entered. @@ -350,7 +350,7 @@ impl Term { } } - /// Flushes internal buffers. + /// Flush internal buffers. /// /// This forces the contents of the internal buffer to be written to /// the terminal. This is unnecessary for unbuffered terminals which @@ -366,25 +366,25 @@ impl Term { Ok(()) } - /// Checks if the terminal is indeed a terminal. + /// Check if the terminal is indeed a terminal. #[inline] pub fn is_term(&self) -> bool { self.is_tty } - /// Checks for common terminal features. + /// Check for common terminal features. #[inline] pub fn features(&self) -> TermFeatures<'_> { TermFeatures(self) } - /// Returns the terminal size in rows and columns or gets sensible defaults. + /// Return the terminal size in rows and columns or gets sensible defaults. #[inline] pub fn size(&self) -> (u16, u16) { self.size_checked().unwrap_or((24, DEFAULT_WIDTH)) } - /// Returns the terminal size in rows and columns. + /// Return the terminal size in rows and columns. /// /// If the size cannot be reliably determined None is returned. #[inline] @@ -392,37 +392,37 @@ impl Term { terminal_size(self) } - /// Moves the cursor to `x` and `y` + /// Move the cursor to `x` and `y` #[inline] pub fn move_cursor_to(&self, x: usize, y: usize) -> io::Result<()> { move_cursor_to(self, x, y) } - /// Moves the cursor up `n` lines + /// Move the cursor up `n` lines #[inline] pub fn move_cursor_up(&self, n: usize) -> io::Result<()> { move_cursor_up(self, n) } - /// Moves the cursor down `n` lines + /// Move the cursor down `n` lines #[inline] pub fn move_cursor_down(&self, n: usize) -> io::Result<()> { move_cursor_down(self, n) } - /// Moves the cursor left `n` lines + /// Move the cursor left `n` lines #[inline] pub fn move_cursor_left(&self, n: usize) -> io::Result<()> { move_cursor_left(self, n) } - /// Moves the cursor down `n` lines + /// Move the cursor down `n` lines #[inline] pub fn move_cursor_right(&self, n: usize) -> io::Result<()> { move_cursor_right(self, n) } - /// Clears the current line. + /// Clear the current line. /// /// The positions the cursor at the beginning of the line again. #[inline] @@ -444,19 +444,19 @@ impl Term { Ok(()) } - /// Clears the entire screen. + /// Clear the entire screen. #[inline] pub fn clear_screen(&self) -> io::Result<()> { clear_screen(self) } - /// Clears the entire screen. + /// Clear the entire screen. #[inline] pub fn clear_to_end_of_screen(&self) -> io::Result<()> { clear_to_end_of_screen(self) } - /// Clears the last char in the the current line. + /// Clear the last `n` chars in the current line. #[inline] pub fn clear_chars(&self, n: usize) -> io::Result<()> { clear_chars(self, n) @@ -470,13 +470,13 @@ impl Term { set_title(title); } - /// Makes cursor visible again + /// Make the cursor visible again #[inline] pub fn show_cursor(&self) -> io::Result<()> { show_cursor(self) } - /// Hides cursor + /// Hide the cursor #[inline] pub fn hide_cursor(&self) -> io::Result<()> { hide_cursor(self) From 56677595b2cfdd08c91f8ab581a540f58293e902 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 20 Jan 2022 10:12:47 +0100 Subject: [PATCH 2/9] doc: Minor grammar edits to documentation comments in term.rs. --- src/term.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/term.rs b/src/term.rs index 128749b8..477bec04 100644 --- a/src/term.rs +++ b/src/term.rs @@ -332,7 +332,7 @@ impl Term { Ok(chars.iter().collect::()) } - /// Read securely a line of input. + /// Read a line of input securely. /// /// This is similar to `read_line` but will not echo the output. This /// also switches the terminal into a different mode where not all @@ -386,7 +386,7 @@ impl Term { /// Return the terminal size in rows and columns. /// - /// If the size cannot be reliably determined None is returned. + /// If the size cannot be reliably determined `None` is returned. #[inline] pub fn size_checked(&self) -> Option<(u16, u16)> { terminal_size(self) @@ -424,7 +424,7 @@ impl Term { /// Clear the current line. /// - /// The positions the cursor at the beginning of the line again. + /// This positions the cursor at the beginning of the current line. #[inline] pub fn clear_line(&self) -> io::Result<()> { clear_line(self) @@ -456,7 +456,7 @@ impl Term { clear_to_end_of_screen(self) } - /// Clear the last `n` chars in the current line. + /// Clear the last `n` chars of the current line. #[inline] pub fn clear_chars(&self, n: usize) -> io::Result<()> { clear_chars(self, n) From 30f80051618ef9eda753bfefe4f7c51601cbda1b Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 20 Jan 2022 10:15:09 +0100 Subject: [PATCH 3/9] doc: Fix doc comments for move_cursor_{left,right}. --- src/term.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/term.rs b/src/term.rs index 477bec04..bbbd7925 100644 --- a/src/term.rs +++ b/src/term.rs @@ -410,13 +410,13 @@ impl Term { move_cursor_down(self, n) } - /// Move the cursor left `n` lines + /// Move the cursor `n` characters to the left #[inline] pub fn move_cursor_left(&self, n: usize) -> io::Result<()> { move_cursor_left(self, n) } - /// Move the cursor down `n` lines + /// Move the cursor `n` characters to the right #[inline] pub fn move_cursor_right(&self, n: usize) -> io::Result<()> { move_cursor_right(self, n) From 7250fd18b4abff0da8aac0f9de9f3b779af5fd0d Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 20 Jan 2022 10:15:27 +0100 Subject: [PATCH 4/9] doc: Clarify doc comments for move_cursor_to and clear_last_lines. --- src/term.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/term.rs b/src/term.rs index bbbd7925..ec6bb3d3 100644 --- a/src/term.rs +++ b/src/term.rs @@ -392,7 +392,7 @@ impl Term { terminal_size(self) } - /// Move the cursor to `x` and `y` + /// Move the cursor to row `x` and column `y`. #[inline] pub fn move_cursor_to(&self, x: usize, y: usize) -> io::Result<()> { move_cursor_to(self, x, y) @@ -430,7 +430,7 @@ impl Term { clear_line(self) } - /// Clear the last `n` lines. + /// Clear the last `n` lines before the current line. /// /// This positions the cursor at the beginning of the first line /// that was cleared. From 0fb376ff6e46bb1171d79813cc55f5f40943e8b2 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 20 Jan 2022 10:21:19 +0100 Subject: [PATCH 5/9] doc: Two minor wording tweaks. --- src/term.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/term.rs b/src/term.rs index ec6bb3d3..e3fb184c 100644 --- a/src/term.rs +++ b/src/term.rs @@ -203,7 +203,7 @@ impl Term { }) } - /// Return the style for the term + /// Return the style for this terminal #[inline] pub fn style(&self) -> Style { match self.inner.target { @@ -214,7 +214,7 @@ impl Term { } } - /// Return the target + /// Return the target of this terminal #[inline] pub fn target(&self) -> TermTarget { self.inner.target.clone() From c75de7eaf27693c83442fc0b4fa7b95feb6fa221 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 17 Feb 2022 13:55:47 +0100 Subject: [PATCH 6/9] doc: End all doc comments with a period. --- src/term.rs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/term.rs b/src/term.rs index 08bda30a..91c20344 100644 --- a/src/term.rs +++ b/src/term.rs @@ -143,7 +143,7 @@ impl Term { term } - /// Return a new unbuffered terminal + /// Return a new unbuffered terminal. #[inline] pub fn stdout() -> Term { Term::with_inner(TermInner { @@ -152,7 +152,7 @@ impl Term { }) } - /// Return a new unbuffered terminal to stderr + /// Return a new unbuffered terminal to stderr. #[inline] pub fn stderr() -> Term { Term::with_inner(TermInner { @@ -161,7 +161,7 @@ impl Term { }) } - /// Return a new buffered terminal + /// Return a new buffered terminal. pub fn buffered_stdout() -> Term { Term::with_inner(TermInner { target: TermTarget::Stdout, @@ -169,7 +169,7 @@ impl Term { }) } - /// Return a new buffered terminal to stderr + /// Return a new buffered terminal to stderr. pub fn buffered_stderr() -> Term { Term::with_inner(TermInner { target: TermTarget::Stderr, @@ -177,7 +177,7 @@ impl Term { }) } - /// Return a terminal for the given Read/Write pair styled-like Stderr. + /// Return a terminal for the given Read/Write pair styled like stderr. #[cfg(unix)] pub fn read_write_pair(read: R, write: W) -> Term where @@ -204,7 +204,7 @@ impl Term { }) } - /// Return the style for this terminal + /// Return the style for this terminal. #[inline] pub fn style(&self) -> Style { match self.inner.target { @@ -215,7 +215,7 @@ impl Term { } } - /// Return the target of this terminal + /// Return the target of this terminal. #[inline] pub fn target(&self) -> TermTarget { self.inner.target.clone() @@ -402,7 +402,7 @@ impl Term { move_cursor_to(self, x, y) } - /// Move the cursor up `n` lines + /// Move the cursor up `n` lines. #[inline] pub fn move_cursor_up(&self, n: usize) -> io::Result<()> { move_cursor_up(self, n) @@ -414,13 +414,13 @@ impl Term { move_cursor_down(self, n) } - /// Move the cursor `n` characters to the left + /// Move the cursor `n` characters to the left. #[inline] pub fn move_cursor_left(&self, n: usize) -> io::Result<()> { move_cursor_left(self, n) } - /// Move the cursor `n` characters to the right + /// Move the cursor `n` characters to the right. #[inline] pub fn move_cursor_right(&self, n: usize) -> io::Result<()> { move_cursor_right(self, n) @@ -466,7 +466,7 @@ impl Term { clear_chars(self, n) } - /// Set the terminal title + /// Set the terminal title. pub fn set_title(&self, title: T) { if !self.is_tty { return; @@ -474,13 +474,13 @@ impl Term { set_title(title); } - /// Make the cursor visible again + /// Make the cursor visible again. #[inline] pub fn show_cursor(&self) -> io::Result<()> { show_cursor(self) } - /// Hide the cursor + /// Hide the cursor. #[inline] pub fn hide_cursor(&self) -> io::Result<()> { hide_cursor(self) From 2ab6622ae1c4886d0702602c9810a17d0abdc06c Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 17 Feb 2022 14:08:30 +0100 Subject: [PATCH 7/9] doc: Improve doc comments for the clear_* functions. The comment for clear_to_end_of_screen was simply wrong. --- src/term.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/term.rs b/src/term.rs index 91c20344..0d42bd4e 100644 --- a/src/term.rs +++ b/src/term.rs @@ -428,7 +428,7 @@ impl Term { /// Clear the current line. /// - /// This positions the cursor at the beginning of the current line. + /// Position the cursor at the beginning of the current line. #[inline] pub fn clear_line(&self) -> io::Result<()> { clear_line(self) @@ -436,8 +436,7 @@ impl Term { /// Clear the last `n` lines before the current line. /// - /// This positions the cursor at the beginning of the first line - /// that was cleared. + /// Position the cursor at the beginning of the first line that was cleared. pub fn clear_last_lines(&self, n: usize) -> io::Result<()> { self.move_cursor_up(n)?; for _ in 0..n { @@ -449,18 +448,21 @@ impl Term { } /// Clear the entire screen. + /// + /// Move the cursor to the upper left corner of the screen. #[inline] pub fn clear_screen(&self) -> io::Result<()> { clear_screen(self) } - /// Clear the entire screen. + /// Clear everything from the current cursor position to the end of the screen. + /// The cursor stays in its position. #[inline] pub fn clear_to_end_of_screen(&self) -> io::Result<()> { clear_to_end_of_screen(self) } - /// Clear the last `n` chars of the current line. + /// Clear the last `n` characters of the current line. #[inline] pub fn clear_chars(&self, n: usize) -> io::Result<()> { clear_chars(self, n) From 9ccc05d081d4a69eb2107c8f9ce3c58c92dea96f Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 17 Feb 2022 14:12:44 +0100 Subject: [PATCH 8/9] doc: Clarify that indices in move_cursor_to are 0-based. --- src/term.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/term.rs b/src/term.rs index 0d42bd4e..ae3c2718 100644 --- a/src/term.rs +++ b/src/term.rs @@ -396,7 +396,7 @@ impl Term { terminal_size(self) } - /// Move the cursor to row `x` and column `y`. + /// Move the cursor to row `x` and column `y`. Values are 0-based. #[inline] pub fn move_cursor_to(&self, x: usize, y: usize) -> io::Result<()> { move_cursor_to(self, x, y) From 60716ea6d02b71de2f594d5784a810ca5c649746 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 17 Feb 2022 14:15:22 +0100 Subject: [PATCH 9/9] Document the behaviour of move_cursor_{left,right,up,down} when called with a larger value than possible. Since that behaviour (moving the cursor as far as possible) is relatively benign, only documenting this and not changing e.g. the function signature seems reasonable. --- src/term.rs | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/src/term.rs b/src/term.rs index ae3c2718..350a7894 100644 --- a/src/term.rs +++ b/src/term.rs @@ -402,25 +402,37 @@ impl Term { move_cursor_to(self, x, y) } - /// Move the cursor up `n` lines. + /// Move the cursor up by `n` lines, if possible. + /// + /// If there are less than `n` lines above the current cursor position, + /// the cursor is moved to the top line of the terminal (i.e., as far up as possible). #[inline] pub fn move_cursor_up(&self, n: usize) -> io::Result<()> { move_cursor_up(self, n) } - /// Move the cursor down `n` lines + /// Move the cursor down by `n` lines, if possible. + /// + /// If there are less than `n` lines below the current cursor position, + /// the cursor is moved to the bottom line of the terminal (i.e., as far down as possible). #[inline] pub fn move_cursor_down(&self, n: usize) -> io::Result<()> { move_cursor_down(self, n) } - /// Move the cursor `n` characters to the left. + /// Move the cursor `n` characters to the left, if possible. + /// + /// If there are fewer than `n` characters to the left of the current cursor position, + /// the cursor is moved to the beginning of the line (i.e., as far to the left as possible). #[inline] pub fn move_cursor_left(&self, n: usize) -> io::Result<()> { move_cursor_left(self, n) } /// Move the cursor `n` characters to the right. + /// + /// If there are fewer than `n` characters to the right of the current cursor position, + /// the cursor is moved to the end of the current line (i.e., as far to the right as possible). #[inline] pub fn move_cursor_right(&self, n: usize) -> io::Result<()> { move_cursor_right(self, n)