Merge pull request console-rs#62 from SzaryKot/more_documentation

Author: pksunkara

src/edit.rs

@@ -6,9 +6,9 @@ use std::{
     process,
 };
 
-/// Launches the default editor edit a string.
+/// Launches the default editor to edit a string.
 ///
-/// Example:
+/// ## Example
 ///
 /// ```rust,no_run
 /// # fn test() -> Result<(), Box<std::error::Error>> {

src/prompts/confirm.rs

@@ -39,6 +39,21 @@ impl<'a> Confirm<'a> {
     }
 
     /// Creates a confirm prompt with a specific theme.
+    /// 
+    /// ## Examples
+    /// ```rust,no_run
+    /// use dialoguer::{
+    ///     Confirm,
+    ///     theme::ColorfulTheme
+    /// };
+    /// 
+    /// # fn main() -> std::io::Result<()> {
+    /// let proceed = Confirm::with_theme(&ColorfulTheme::default())
+    ///     .with_prompt("Do you wish to continue?")
+    ///     .interact()?;
+    /// #    Ok(())
+    /// # }
+    /// ```
     pub fn with_theme(theme: &'a dyn Theme) -> Confirm<'a> {
         Confirm {
             prompt: "".into(),
@@ -60,13 +75,16 @@ impl<'a> Confirm<'a> {
         self.with_prompt(text)
     }
 
-    /// Overrides the default.
+    /// Overrides the default output if user pushes enter key without inputing any character.
+    /// Character corresponding to the default choice (e.g `Y` if default is `true`) will be uppercased in the displayed prompt.
+    /// 
+    /// The default output is true.
     pub fn default(&mut self, val: bool) -> &mut Confirm<'a> {
         self.default = val;
         self
     }
 
-    /// Disables or enables the default value display.
+    /// Disables or enables display of options user can choose from.
     ///
     /// The default is to append `[y/n]` to the prompt to tell the
     /// user which keys to press. This also renders the default choice
@@ -78,13 +96,29 @@ impl<'a> Confirm<'a> {
 
     /// Enables user interaction and returns the result.
     ///
-    /// If the user confirms the result is `true`, `false` otherwise.
+    /// If the user confirms the result is `true`, `false` if declines or default (configured in [default](#method.default)) if pushes enter.
+    /// Otherwise function discards input waiting for valid one.
+    /// 
     /// The dialog is rendered on stderr.
     pub fn interact(&self) -> io::Result<bool> {
         self.interact_on(&Term::stderr())
     }
 
-    /// Like `interact` but allows a specific terminal to be set.
+    /// Like [interact](#method.interact) but allows a specific terminal to be set.
+    /// 
+    /// ## Examples 
+    /// 
+    /// ```rust,nor_run
+    /// use dialoguer::Confirm;
+    /// use console::Term;
+    /// 
+    /// # fn main() -> std::io::Result<()> {
+    /// let proceed = Confirm::new()
+    ///     .with_prompt("Do you wish to continue?")
+    ///     .interact_on(&Term::stderr())?;
+    /// #   Ok(())
+    /// # }
+    /// ```
     pub fn interact_on(&self, term: &Term) -> io::Result<bool> {
         let mut render = TermThemeRenderer::new(term, self.theme);
 

src/prompts/input.rs

@@ -16,12 +16,19 @@ use console::{Key, Term};
 /// ## Example usage
 ///
 /// ```rust,no_run
-/// # fn test() -> Result<(), Box<std::error::Error>> {
 /// use dialoguer::Input;
 ///
-/// let name = Input::<String>::new().with_prompt("Your name").interact()?;
-/// println!("Name: {}", name);
-/// # Ok(()) } fn main() { test().unwrap(); }
+/// let input : String = Input::new()
+///     .with_prompt("Tea or coffee?")
+///     .with_initial_text("Yes")
+///     .default("No".into())
+///     .interact_text()?;
+/// ```
+/// It can also be used with turbofish notation:
+/// 
+/// ```rust,no_run
+/// let input = Input::<String>::new()
+///     .interact_text()?;
 /// ```
 pub struct Input<'a, T> {
     prompt: String,
@@ -72,7 +79,7 @@ where
         self
     }
 
-    /// Sets whether the default can be editable.
+    /// Sets initial text that user can accept or erase.
     pub fn with_initial_text<S: Into<String>>(&mut self, val: S) -> &mut Input<'a, T> {
         self.initial_text = Some(val.into());
         self
@@ -81,7 +88,7 @@ where
     /// Sets a default.
     ///
     /// Out of the box the prompt does not have a default and will continue
-    /// to display until the user hit enter.  If a default is set the user
+    /// to display until the user inputs something and hits enter. If a default is set the user
     /// can instead accept the default with enter.
     pub fn default(&mut self, value: T) -> &mut Input<'a, T> {
         self.default = Some(value);
@@ -98,8 +105,10 @@ where
 
     /// Disables or enables the default value display.
     ///
-    /// The default is to append `[default]` to the prompt to tell the
-    /// user that a default is acceptable.
+    /// The default behaviour is to append [`default`] to the prompt to tell the
+    /// user what is the default value.
+    /// 
+    /// This method does not affect existance of default value, only its display in the prompt! 
     pub fn show_default(&mut self, val: bool) -> &mut Input<'a, T> {
         self.show_default = val;
         self

src/prompts/multi_select.rs

@@ -5,6 +5,16 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme};
 use console::{Key, Term};
 
 /// Renders a multi select prompt.
+/// 
+/// ## Example usage
+/// ```rust,no_run
+/// use dialoguer::MultiSelect;
+/// 
+/// let items = vec![("Option 1", true), ("Option 2", false)];
+/// let chosen : Vec<usize> = MultiSelect::new()
+///     .items(&items)
+///     .interact()?;
+/// ```
 pub struct MultiSelect<'a> {
     defaults: Vec<bool>,
     items: Vec<String>,
@@ -112,7 +122,7 @@ impl<'a> MultiSelect<'a> {
         self.interact_on(&Term::stderr())
     }
 
-    /// Like `interact` but allows a specific terminal to be set.
+    /// Like [interact](#method.interact) but allows a specific terminal to be set.
     pub fn interact_on(&self, term: &Term) -> io::Result<Vec<usize>> {
         let mut page = 0;
 

src/prompts/sort.rs

@@ -5,6 +5,19 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme};
 use console::{Key, Term};
 
 /// Renders a sort prompt.
+/// 
+/// Returns list of indices in original items list sorted according to user input.
+/// 
+/// ## Example usage
+/// ```rust,no_run
+/// use dialoguer::Sort;
+///
+/// let items_to_order = vec!["Item 1", "Item 2", "Item 3"];
+/// let ordered = Sort::new()
+///     .with_prompt("Order the items")
+///     .items(&items_to_order)
+///     .interact()?;
+/// ```
 pub struct Sort<'a> {
     items: Vec<String>,
     prompt: Option<String>,
@@ -44,7 +57,7 @@ impl<'a> Sort<'a> {
 
     /// Sets the clear behavior of the menu.
     ///
-    /// The default is to clear the menu.
+    /// The default is to clear the menu after user interaction.
     pub fn clear(&mut self, val: bool) -> &mut Sort<'a> {
         self.clear = val;
         self
@@ -81,7 +94,7 @@ impl<'a> Sort<'a> {
         self.interact_on(&Term::stderr())
     }
 
-    /// Like `interact` but allows a specific terminal to be set.
+    /// Like [interact](#method.interact) but allows a specific terminal to be set.
     pub fn interact_on(&self, term: &Term) -> io::Result<Vec<usize>> {
         let mut page = 0;
 

src/validate.rs

@@ -1,5 +1,10 @@
 //! Provides validation for text inputs
 use std::fmt::{Debug, Display};
+
+/// Trait for input validators.
+/// 
+/// A generic implementation for `Fn(&str) -> Result<(), E>` is provided
+/// to facilitate development.
 pub trait Validator {
     type Err: Debug + Display;