From 495b648b3a69612b875f1ef3dbbb6728ea086886 Mon Sep 17 00:00:00 2001
From: gwenn <gtreguier@gmail.com>
Date: Tue, 12 Sep 2017 11:39:38 +0200
Subject: [PATCH] Fix some rustdoc
---
src/completion.rs | 1 +
src/config.rs | 7 +++++--
src/history.rs | 23 +++++++++++++----------
src/lib.rs | 8 +++++++-
4 files changed, 26 insertions(+), 13 deletions(-)
diff --git a/src/completion.rs b/src/completion.rs
index 8bcc76a1..8991c028 100644
--- a/src/completion.rs
+++ b/src/completion.rs
@@ -17,6 +17,7 @@ pub trait Completer {
/// Takes the currently edited `line` with the cursor `pos`ition and
/// returns the start position and the completion candidates for the
/// partial word to be completed.
+ ///
/// "ls /usr/loc" => Ok((3, vec!["/usr/local/"]))
fn complete(&self, line: &str, pos: usize) -> Result<(usize, Vec<String>)>;
/// Updates the edited `line` with the `elected` candidate.
diff --git a/src/config.rs b/src/config.rs
index 531777bb..82f4ab05 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -31,6 +31,7 @@ impl Config {
/// Tell if lines which match the previous history entry are saved or not
/// in the history list.
+ ///
/// By default, they are ignored.
pub fn history_duplicates(&self) -> HistoryDuplicates {
self.history_duplicates
@@ -38,6 +39,7 @@ impl Config {
/// Tell if lines which begin with a space character are saved or not in
/// the history list.
+ ///
/// By default, they are saved.
pub fn history_ignore_space(&self) -> bool {
self.history_ignore_space
@@ -119,6 +121,7 @@ impl Builder {
/// Tell if lines which match the previous history entry are saved or not
/// in the history list.
+ ///
/// By default, they are ignored.
pub fn history_ignore_dups(mut self, yes: bool) -> Builder {
self.p.history_duplicates = if yes {
@@ -131,6 +134,7 @@ impl Builder {
/// Tell if lines which begin with a space character are saved or not in
/// the history list.
+ ///
/// By default, they are saved.
pub fn history_ignore_space(mut self, yes: bool) -> Builder {
self.p.history_ignore_space = yes;
@@ -144,8 +148,7 @@ impl Builder {
}
/// The number of possible completions that determines when the user is
- /// asked
- /// whether the list of possibilities should be displayed.
+ /// asked whether the list of possibilities should be displayed.
pub fn completion_prompt_limit(mut self, completion_prompt_limit: usize) -> Builder {
self.p.completion_prompt_limit = completion_prompt_limit;
self
diff --git a/src/history.rs b/src/history.rs
index 3fe60dca..af13052c 100644
--- a/src/history.rs
+++ b/src/history.rs
@@ -79,11 +79,11 @@ impl History {
true
}
- /// Returns the number of entries in the history.
+ /// Return the number of entries in the history.
pub fn len(&self) -> usize {
self.entries.len()
}
- /// Returns true if the history has no entry.
+ /// Return true if the history has no entry.
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
@@ -91,8 +91,9 @@ impl History {
/// Set the maximum length for the history. This function can be called even
/// if there is already some history, the function will make sure to retain
/// just the latest `len` elements if the new history length value is
- /// smaller
- /// than the amount of items already inside the history.
+ /// smaller than the amount of items already inside the history.
+ ///
+ /// Like [stifle_history](http://cnswww.cns.cwru.edu/php/chet/readline/history.html#IDX11).
pub fn set_max_len(&mut self, len: usize) {
self.max_len = len;
if len == 0 {
@@ -108,10 +109,10 @@ impl History {
}
/// Save the history in the specified file.
- /// TODO append_history
- /// http://cnswww.cns.cwru.edu/php/chet/readline/history.html#IDX30
- /// TODO history_truncate_file
- /// http://cnswww.cns.cwru.edu/php/chet/readline/history.html#IDX31
+ // TODO append_history
+ // http://cnswww.cns.cwru.edu/php/chet/readline/history.html#IDX30
+ // TODO history_truncate_file
+ // http://cnswww.cns.cwru.edu/php/chet/readline/history.html#IDX31
pub fn save<P: AsRef<Path> + ?Sized>(&self, path: &P) -> Result<()> {
use std::io::{BufWriter, Write};
@@ -133,8 +134,8 @@ impl History {
/// Load the history from the specified file.
///
- /// # Failure
- /// Will return `Err` if path does not already exist.
+ /// # Errors
+ /// Will return `Err` if path does not already exist or could not be read.
pub fn load<P: AsRef<Path> + ?Sized>(&mut self, path: &P) -> Result<()> {
use std::io::{BufRead, BufReader};
@@ -152,8 +153,10 @@ impl History {
}
/// Search history (start position inclusive [0, len-1]).
+ ///
/// Return the absolute index of the nearest history entry that matches
/// `term`.
+ ///
/// Return None if no entry contains `term` between [start, len -1] for
/// forward search
/// or between [0, start] for reverse search.
diff --git a/src/lib.rs b/src/lib.rs
index d76db7c1..bd71b0b3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1085,10 +1085,12 @@ pub struct Editor<C: Completer> {
}
impl<C: Completer> Editor<C> {
+ /// Create an editor with the default configuration
pub fn new() -> Editor<C> {
Self::with_config(Config::default())
}
+ /// Create an editor with a specific configuration.
pub fn with_config(config: Config) -> Editor<C> {
let term = Terminal::new();
Editor {
@@ -1101,7 +1103,11 @@ impl<C: Completer> Editor<C> {
}
}
- /// This method will read a line from STDIN and will display a `prompt`
+ /// This method will read a line from STDIN and will display a `prompt`.
+ ///
+ /// It uses terminal-style interaction if `stdin` is connected to a terminal.
+ /// Otherwise (e.g., if `stdin` is a pipe or the terminal is not supported),
+ /// it uses file-style interaction.
pub fn readline(&mut self, prompt: &str) -> Result<String> {
if self.term.is_unsupported() {
debug!(target: "rustyline", "unsupported terminal");
--
GitLab