From c33efbac6f00370d1942351d50ec10a1411f2792 Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Thu, 21 Dec 2023 02:16:52 +0530 Subject: [PATCH 1/8] doc: Write more docs on the Pager type --- src/pager.rs | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/src/pager.rs b/src/pager.rs index 405baf5..944dc15 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -1,3 +1,5 @@ +//! Proivdes the [Pager] type + use crate::{error::MinusError, input, minus_core::commands::Command, ExitStrategy, LineNumbers}; use crossbeam_channel::{Receiver, Sender}; use std::fmt; @@ -5,17 +7,46 @@ use std::fmt; #[cfg(feature = "search")] use crate::search::SearchOpts; -/// A pager acts as a middleman for communication between the main application -/// and the user with the core functions of minus +/// A communicationA bridge between the main application and the pager. +/// +/// The [Pager] type which is a bridge between your application and running +/// the running pager. Its the single most important type with which you will be interacting the +/// most while working with minus. It allows you to send data, configure UI settings and also +/// configure the key/mouse bindings. /// -/// It consists of a [`crossbeam_channel::Sender`] and [`crossbeam_channel::Receiver`] +/// This neat thing about this is that not allows you to trasmits data while the pager is running +/// but also if the pager hsen't been started. This means that you can preconfigure the pager +/// before calling the initialization methods which most applications likely want to do. +/// +/// It consists of a [`crossbeam_channel::Sender`] and [`crossbeam_channel::Receiver`] /// pair. When a method like [`set_text`](Pager::set_text) or [`push_str`](Pager::push_str) -/// is called, the function takes the input. wraps it in the appropriate event -/// type and transmits it through the sender held inside the this. +/// is called, the function takes the input. wraps it in the appropriate command +/// variant and transmits it through the sender held inside the this. /// /// The receiver part of the channel is continuously polled by the pager for events. Depending -/// on the type of event that occurs, the pager will either redraw the screen or update -/// the [PagerState](crate::state::PagerState) +/// on the type of event that occurs, the pager will perform the required action. +/// +/// [Pager] also implements the [fmt::Write] trait which means you can directly call [write!] and +/// [writeln!] macros on it. For example, you can easily do this +/// +/// ``` +/// use minus::Pager; +/// use std::fmt::Write; +/// +/// const WHO: &str = "World"; +/// let mut pager = Pager::new(); +/// writeln!(pager, "Hello {WHO}").unwrap(); +/// ``` +/// This appends `Hello World` to the end of minus's buffer. You can achieve the same using the +/// [Pager::push_str] function like this +/// ``` +/// use minus::Pager; +/// use std::fmt::Write; +/// +/// const WHO: &str = "World"; +/// let pager = Pager::new(); +/// pager.push_str(format!("Hello {WHO}\n")).unwrap(); +/// ``` #[derive(Clone)] pub struct Pager { pub(crate) tx: Sender, From f8dfc9474029ca210067ff1846c63f8538f48d6e Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Thu, 21 Dec 2023 17:09:33 +0530 Subject: [PATCH 2/8] doc(pager): Improve docs for Pager::send_message() --- src/pager.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/pager.rs b/src/pager.rs index 944dc15..9a75f39 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -26,7 +26,7 @@ use crate::search::SearchOpts; /// The receiver part of the channel is continuously polled by the pager for events. Depending /// on the type of event that occurs, the pager will perform the required action. /// -/// [Pager] also implements the [fmt::Write] trait which means you can directly call [write!] and +/// [Pager] also implements the [std::fmt::Write] trait which means you can directly call [write!] and /// [writeln!] macros on it. For example, you can easily do this /// /// ``` @@ -156,6 +156,10 @@ impl Pager { /// Display a temporary message at the prompt area /// + /// A message is a piece of text that the main application can ask minus to display at the + /// prompt location. The text message is temporary and will get cleared whenever the use + /// rdoes a action on the terminal like pressing a key or scrolling using the mouse. + /// /// # Panics /// This function panics if the given text contains newline characters. /// This is because, the pager reserves only one line for showing the prompt From 6f8ff4bbfca0fc40903858d4a361f5880dd3295a Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Sun, 24 Dec 2023 11:43:00 +0530 Subject: [PATCH 3/8] doc(pager): Trim down docs for Pager::send_message() --- src/pager.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/pager.rs b/src/pager.rs index 9a75f39..41cd55a 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -154,10 +154,9 @@ impl Pager { Ok(self.tx.send(Command::SetPrompt(text))?) } - /// Display a temporary message at the prompt area + /// Send a message to be displayed the prompt area /// - /// A message is a piece of text that the main application can ask minus to display at the - /// prompt location. The text message is temporary and will get cleared whenever the use + /// The text message is temporary and will get cleared whenever the use /// rdoes a action on the terminal like pressing a key or scrolling using the mouse. /// /// # Panics From 3345201f6c5f00fa8307570f058755588a888f8c Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Wed, 27 Dec 2023 13:12:33 +0530 Subject: [PATCH 4/8] doc(pager): Cleanup dev docs for Pager type --- src/pager.rs | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/src/pager.rs b/src/pager.rs index 41cd55a..d8096c9 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -18,14 +18,6 @@ use crate::search::SearchOpts; /// but also if the pager hsen't been started. This means that you can preconfigure the pager /// before calling the initialization methods which most applications likely want to do. /// -/// It consists of a [`crossbeam_channel::Sender`] and [`crossbeam_channel::Receiver`] -/// pair. When a method like [`set_text`](Pager::set_text) or [`push_str`](Pager::push_str) -/// is called, the function takes the input. wraps it in the appropriate command -/// variant and transmits it through the sender held inside the this. -/// -/// The receiver part of the channel is continuously polled by the pager for events. Depending -/// on the type of event that occurs, the pager will perform the required action. -/// /// [Pager] also implements the [std::fmt::Write] trait which means you can directly call [write!] and /// [writeln!] macros on it. For example, you can easily do this /// @@ -88,11 +80,10 @@ impl Pager { /// Appends text to the pager output. /// /// You can also use [`write!`]/[`writeln!`] macros to append data to the pager. - /// The implementation basically calls this function internally. - /// - /// One difference between using the macros and this function is that this does - /// not require `Pager` to be declared mutable while in order to use the macros, - /// you need to declare the `Pager` as mutable. + /// The implementation basically calls this function internally. One difference + /// between using the macros and this function is that this does not require `Pager` + /// to be declared mutable while in order to use the macros, you need to declare + /// the `Pager` as mutable. /// /// # Errors /// This function will return a [`Err(MinusError::Communication)`](MinusError::Communication) if the data From 37f136b5dcc10dea3d51ed8b8a568abd74782315 Mon Sep 17 00:00:00 2001 From: Arijit Dey <65700195+arijit79@users.noreply.github.com> Date: Thu, 28 Dec 2023 14:09:36 +0530 Subject: [PATCH 5/8] doc(pager): fixed typo Co-authored-by: TornaxO7 --- src/pager.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pager.rs b/src/pager.rs index d8096c9..53881ab 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -7,7 +7,7 @@ use std::fmt; #[cfg(feature = "search")] use crate::search::SearchOpts; -/// A communicationA bridge between the main application and the pager. +/// A communication bridge between the main application and the pager. /// /// The [Pager] type which is a bridge between your application and running /// the running pager. Its the single most important type with which you will be interacting the From 6c1d735508ebe588d911fbeaeeac095745c55a4f Mon Sep 17 00:00:00 2001 From: Arijit Dey <65700195+arijit79@users.noreply.github.com> Date: Thu, 28 Dec 2023 14:17:43 +0530 Subject: [PATCH 6/8] doc(pager): Trim docs for writeln! portion Co-authored-by: TornaxO7 --- src/pager.rs | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/src/pager.rs b/src/pager.rs index 53881ab..a1e40d3 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -27,18 +27,12 @@ use crate::search::SearchOpts; /// /// const WHO: &str = "World"; /// let mut pager = Pager::new(); -/// writeln!(pager, "Hello {WHO}").unwrap(); -/// ``` -/// This appends `Hello World` to the end of minus's buffer. You can achieve the same using the -/// [Pager::push_str] function like this -/// ``` -/// use minus::Pager; -/// use std::fmt::Write; /// -/// const WHO: &str = "World"; -/// let pager = Pager::new(); +/// // this appends `Hello World` to the end of minus's buffer +/// // and this... +/// writeln!(pager, "Hello {WHO}").unwrap(); +/// // ... equals this /// pager.push_str(format!("Hello {WHO}\n")).unwrap(); -/// ``` #[derive(Clone)] pub struct Pager { pub(crate) tx: Sender, From cb7e6066bf4ab4a0ea250a7c09156c4e20d646c1 Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Thu, 28 Dec 2023 14:25:08 +0530 Subject: [PATCH 7/8] doc(pager): Fix some wording --- src/pager.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/pager.rs b/src/pager.rs index a1e40d3..a660f3c 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -28,10 +28,9 @@ use crate::search::SearchOpts; /// const WHO: &str = "World"; /// let mut pager = Pager::new(); /// -/// // this appends `Hello World` to the end of minus's buffer -/// // and this... +/// // This appends `Hello World` to the end of minus's buffer /// writeln!(pager, "Hello {WHO}").unwrap(); -/// // ... equals this +/// // which is also equivalent to writing this /// pager.push_str(format!("Hello {WHO}\n")).unwrap(); #[derive(Clone)] pub struct Pager { From 683af0bc2e2d020782c269638fa1b0c51bbd313c Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Sat, 30 Dec 2023 02:16:33 +0530 Subject: [PATCH 8/8] doc(pager): Improve wording in Pager docs --- src/pager.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/pager.rs b/src/pager.rs index a660f3c..74ce687 100644 --- a/src/pager.rs +++ b/src/pager.rs @@ -14,9 +14,11 @@ use crate::search::SearchOpts; /// most while working with minus. It allows you to send data, configure UI settings and also /// configure the key/mouse bindings. /// -/// This neat thing about this is that not allows you to trasmits data while the pager is running -/// but also if the pager hsen't been started. This means that you can preconfigure the pager -/// before calling the initialization methods which most applications likely want to do. +/// You can +/// - send data and +/// - set configuration options +/// +/// before or while the pager is running. /// /// [Pager] also implements the [std::fmt::Write] trait which means you can directly call [write!] and /// [writeln!] macros on it. For example, you can easily do this