Extend and tweak documention in select.rs and theme.rs.

src/prompts/confirm.rs

@@ -4,7 +4,7 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme};
 
 use console::{Key, Term};
 
-/// Renders a confirm prompt.
+/// Render a confirmation prompt.
 ///
 /// ## Example usage
 ///
@@ -20,10 +20,15 @@ use console::{Key, Term};
 /// # Ok(()) } fn main() { test().unwrap(); }
 /// ```
 pub struct Confirm<'a> {
+    /// Message of the confirmation prompt.
     prompt: String,
+    /// Whether to report the user's choice after selection.
     report: bool,
+    /// default option for the prompt (if any)
     default: Option<bool>,
+    /// if true, show the default value to the user, see [`show_default`](#method::show_default)
     show_default: bool,
+    /// when to react to user input, see [`wait_for_newline`](#methhod::wait_for_newline)
     wait_for_newline: bool,
     theme: &'a dyn Theme,
 }
@@ -35,20 +40,20 @@ impl Default for Confirm<'static> {
 }
 
 impl Confirm<'static> {
-    /// Creates a confirm prompt.
+    /// Create a confirmation prompt.
     pub fn new() -> Self {
         Self::with_theme(&SimpleTheme)
     }
 }
 
 impl Confirm<'_> {
-    /// Sets the confirm prompt.
+    /// Set the confirmation prompt message.
     pub fn with_prompt<S: Into<String>>(&mut self, prompt: S) -> &mut Self {
         self.prompt = prompt.into();
         self
     }
 
-    /// Indicates whether or not to report the chosen selection after interaction.
+    /// Indicate whether or not to report the chosen selection after interaction.
     ///
     /// The default is to report the chosen selection.
     pub fn report(&mut self, val: bool) -> &mut Self {
@@ -76,47 +81,50 @@ impl Confirm<'_> {
         self
     }
 
-    /// Sets a default.
+    /// Set a default choice for the prompt.
     ///
-    /// Out of the box the prompt does not have a default and will continue
-    /// to display until the user inputs something and hits enter. If a default is set the user
-    /// can instead accept the default with enter.
+    /// Out of the box, the prompt does not have a default choice and will continue
+    /// to display until the user inputs something and hits enter. If a default is set,
+    /// the user can also accept the default with enter.
     pub fn default(&mut self, val: bool) -> &mut Self {
         self.default = Some(val);
         self
     }
 
-    /// Disables or enables the default value display.
+    /// Disable or enable the default value display.
     ///
     /// The default is to append the default value to the prompt to tell the user.
     pub fn show_default(&mut self, val: bool) -> &mut Self {
         self.show_default = val;
         self
     }
 
-    /// Enables user interaction and returns the result.
+    /// Enable user interaction and return the result.
     ///
     /// The dialog is rendered on stderr.
     ///
-    /// Result contains `bool` if user answered "yes" or "no" or `default` (configured in [`default`](Self::default) if pushes enter.
-    /// This unlike [`interact_opt`](Self::interact_opt) does not allow to quit with 'Esc' or 'q'.
+    /// Result contains `bool` if the user answered "yes" or "no" or `default`
+    /// (configured in [`default`](Self::default)) if they pushed enter.
+    /// Unlike [`interact_opt`](Self::interact_opt), this does not allow
+    /// to quit the dialog with 'Esc' or 'q'.
     #[inline]
     pub fn interact(&self) -> io::Result<bool> {
         self.interact_on(&Term::stderr())
     }
 
-    /// Enables user interaction and returns the result.
+    /// Enable user interaction and return the result.
     ///
     /// The dialog is rendered on stderr.
     ///
-    /// Result contains `Some(bool)` if user answered "yes" or "no" or `Some(default)` (configured in [`default`](Self::default)) if pushes enter,
-    /// or `None` if user cancelled with 'Esc' or 'q'.
+    /// Result contains `Some(bool)` if the user answered "yes" or "no" or `Some(default)`
+    /// (configured in [`default`](Self::default)) if they pushed enter,
+    /// or `None` if the user cancelled the prompt with 'Esc' or 'q'.
     #[inline]
     pub fn interact_opt(&self) -> io::Result<Option<bool>> {
         self.interact_on_opt(&Term::stderr())
     }
 
-    /// Like [interact](#method.interact) but allows a specific terminal to be set.
+    /// Like [interact](#method.interact) but allow a specific terminal to be set.
     ///
     /// ## Examples
     ///
@@ -178,7 +186,7 @@ impl Confirm<'_> {
         let rv;
 
         if self.wait_for_newline {
-            // Waits for user input and for the user to hit the Enter key
+            // Wait for user input and for the user to hit the Enter key
             // before validation.
             let mut value = default_if_show;
 
@@ -215,8 +223,8 @@ impl Confirm<'_> {
                 render.confirm_prompt(&self.prompt, value)?;
             }
         } else {
-            // Default behavior: matches continuously on every keystroke,
-            // and does not wait for user to hit the Enter key.
+            // Default behavior: match continuously on every keystroke,
+            // and do not wait for the user to hit the Enter key.
             loop {
                 let input = term.read_key()?;
                 let value = match input {
@@ -246,7 +254,7 @@ impl Confirm<'_> {
 }
 
 impl<'a> Confirm<'a> {
-    /// Creates a confirm prompt with a specific theme.
+    /// Create a confirm prompt with a specific theme.
     ///
     /// ## Examples
     /// ```rust,no_run

src/prompts/password.rs

@@ -5,7 +5,7 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme};
 use console::Term;
 use zeroize::Zeroizing;
 
-/// Renders a password input prompt.
+/// Render a password input prompt.
 ///
 /// ## Example usage
 ///
@@ -20,10 +20,14 @@ use zeroize::Zeroizing;
 /// # Ok(()) } fn main() { test().unwrap(); }
 /// ```
 pub struct Password<'a> {
+    /// Message of the confirmation prompt.
     prompt: String,
+    /// Whether to print a confirmation message after selecting a password.
     report: bool,
     theme: &'a dyn Theme,
+    /// Whether an empty password is allowed.
     allow_empty_password: bool,
+    // Confirmation prompt for passwords: see [`with_confirmation`](#method::with_confirmation).
     confirmation_prompt: Option<(String, String)>,
 }
 
@@ -34,28 +38,32 @@ impl Default for Password<'static> {
 }
 
 impl Password<'static> {
-    /// Creates a password input prompt.
+    /// Create a password input prompt.
     pub fn new() -> Password<'static> {
         Self::with_theme(&SimpleTheme)
     }
 }
 
 impl Password<'_> {
-    /// Sets the password input prompt.
+    /// Set the password input prompt.
     pub fn with_prompt<S: Into<String>>(&mut self, prompt: S) -> &mut Self {
         self.prompt = prompt.into();
         self
     }
 
-    /// Indicates whether to report confirmation after interaction.
+    /// Indicate whether to report a confirmation after interaction.
     ///
     /// The default is to report.
     pub fn report(&mut self, val: bool) -> &mut Self {
         self.report = val;
         self
     }
 
-    /// Enables confirmation prompting.
+    /// Enable prompting for confirmation of the password:
+    /// if set, the user must type the same password again to confirm their choice.
+    ///
+    /// `prompt` is the prompt message for the confirmation prompt,
+    /// `mismatch_err` the error message printed upon mismatching passwords.
     pub fn with_confirmation<A, B>(&mut self, prompt: A, mismatch_err: B) -> &mut Self
     where
         A: Into<String>,
@@ -65,27 +73,25 @@ impl Password<'_> {
         self
     }
 
-    /// Allows/Disables empty password.
+    /// Allow/disallow entering an empty password.
     ///
-    /// By default this setting is set to false (i.e. password is not empty).
+    /// By default this setting is set to false (i.e. empty passwords are not allowed).
     pub fn allow_empty_password(&mut self, allow_empty_password: bool) -> &mut Self {
         self.allow_empty_password = allow_empty_password;
         self
     }
 
-    /// Enables user interaction and returns the result.
+    /// Enable user interaction and return the result.
     ///
     /// If the user confirms the result is `true`, `false` otherwise.
     /// The dialog is rendered on stderr.
     pub fn interact(&self) -> io::Result<String> {
         self.interact_on(&Term::stderr())
     }
 
-    /// Like `interact` but allows a specific terminal to be set.
+    /// Like [`interact`](#method::interact), but allow a specific terminal to be set.
     pub fn interact_on(&self, term: &Term) -> io::Result<String> {
         let mut render = TermThemeRenderer::new(term, self.theme);
-        render.set_prompts_reset_height(false);
-
         loop {
             let password = Zeroizing::new(self.prompt_password(&mut render, &self.prompt)?);
 
@@ -131,7 +137,7 @@ impl Password<'_> {
 }
 
 impl<'a> Password<'a> {
-    /// Creates a password input prompt with a specific theme.
+    /// Create a password input prompt with a specific theme.
     pub fn with_theme(theme: &'a dyn Theme) -> Self {
         Self {
             prompt: "".into(),

src/prompts/select.rs

@@ -5,7 +5,7 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme};
 
 use console::{Key, Term};
 
-/// Renders a select prompt.
+/// Render a selection prompt.
 ///
 /// User can select from one or more options.
 /// Interaction returns index of an item selected in the order they appear in `item` invocation or `items` slice.
@@ -35,12 +35,19 @@ use console::{Key, Term};
 /// }
 /// ```
 pub struct Select<'a> {
+    /// The initial selected element when the selection menu is rendered,
+    /// indicated by its index in [`items`](#field::items).
     default: usize,
+    /// Items the user can select.
     items: Vec<String>,
+    /// Message of the selection prompt.
     prompt: Option<String>,
+    /// whether to report the selected value after interaction
     report: bool,
+    /// whether the selection menu should be erased from the screen after interaction
     clear: bool,
     theme: &'a dyn Theme,
+    /// Maximal number of items on page (`None` if unbounded).
     max_length: Option<usize>,
 }
 
@@ -51,36 +58,34 @@ impl Default for Select<'static> {
 }
 
 impl Select<'static> {
-    /// Creates a select prompt builder with default theme.
+    /// Create a selection prompt builder with default theme.
     pub fn new() -> Self {
         Self::with_theme(&SimpleTheme)
     }
 }
 
 impl Select<'_> {
-    /// Indicates whether select menu should be erased from the screen after interaction.
+    /// Indicate whether the selection menu should be erased from the screen after interaction.
     ///
     /// The default is to clear the menu.
     pub fn clear(&mut self, val: bool) -> &mut Self {
         self.clear = val;
         self
     }
 
-    /// Sets initial selected element when select menu is rendered
+    /// Set the initial selected element when the selection menu is rendered.
     ///
-    /// Element is indicated by the index at which it appears in `item` method invocation or `items` slice.
+    /// The default element is indicated by the index at which it appears in the `item` method invocation or the `items` slice.
     pub fn default(&mut self, val: usize) -> &mut Self {
         self.default = val;
         self
     }
 
-    /// Sets an optional max length for a page.
-    ///
-    /// Max length is disabled by None
+    /// Set an optional max length for a page.
     pub fn max_length(&mut self, val: usize) -> &mut Self {
         // Paging subtracts two from the capacity, paging does this to
         // make an offset for the page indicator. So to make sure that
-        // we can show the intended amount of items we need to add two
+        // we can show the intended amount of items, we need to add two
         // to our value.
         self.max_length = Some(val + 2);
         self
@@ -106,7 +111,7 @@ impl Select<'_> {
         self
     }
 
-    /// Adds multiple items to the selector.
+    /// Add multiple items to the selector.
     ///
     /// ## Examples
     /// ```rust,no_run
@@ -130,7 +135,7 @@ impl Select<'_> {
         self
     }
 
-    /// Sets the select prompt.
+    /// Set the selection prompt.
     ///
     /// By default, when a prompt is set the system also prints out a confirmation after
     /// the selection. You can opt-out of this with [`report`](#method.report).
@@ -155,26 +160,26 @@ impl Select<'_> {
         self
     }
 
-    /// Indicates whether to report the selected value after interaction.
+    /// Indicate whether to report the selected value after interaction.
     ///
     /// The default is to report the selection.
     pub fn report(&mut self, val: bool) -> &mut Self {
         self.report = val;
         self
     }
 
-    /// Enables user interaction and returns the result.
+    /// Enable user interaction and return the result.
     ///
     /// The user can select the items with the 'Space' bar or 'Enter' and the index of selected item will be returned.
     /// The dialog is rendered on stderr.
     /// Result contains `index` if user selected one of items using 'Enter'.
-    /// This unlike [`interact_opt`](Self::interact_opt) does not allow to quit with 'Esc' or 'q'.
+    /// Unlike [`interact_opt`](Self::interact_opt), this does not allow to quit with 'Esc' or 'q'.
     #[inline]
     pub fn interact(&self) -> io::Result<usize> {
         self.interact_on(&Term::stderr())
     }
 
-    /// Enables user interaction and returns the result.
+    /// Enable user interaction and return the result.
     ///
     /// The user can select the items with the 'Space' bar or 'Enter' and the index of selected item will be returned.
     /// The dialog is rendered on stderr.
@@ -350,7 +355,7 @@ impl Select<'_> {
 }
 
 impl<'a> Select<'a> {
-    /// Creates a select prompt builder with a specific theme.
+    /// Create a selection prompt builder with a specific theme.
     ///
     /// ## Examples
     /// ```rust,no_run

src/prompts/sort.rs

@@ -57,7 +57,7 @@ impl Sort<'_> {
 
     /// Sets an optional max length for a page
     ///
-    /// Max length is disabled by None
+    /// Max length is disabled by `None`
     pub fn max_length(&mut self, val: usize) -> &mut Self {
         // Paging subtracts two from the capacity, paging does this to
         // make an offset for the page indicator. So to make sure that