docs: Clean up

Author: epage

src/process.rs

@@ -2,13 +2,13 @@
 
 use crate::error::Error;
 use nix;
-use nix::fcntl::{OFlag, open};
+use nix::fcntl::{open, OFlag};
 use nix::libc::STDERR_FILENO;
-use nix::pty::{PtyMaster, grantpt, posix_openpt, unlockpt};
+use nix::pty::{grantpt, posix_openpt, unlockpt, PtyMaster};
 pub use nix::sys::{signal, wait};
 use nix::sys::{stat, termios};
 use nix::unistd::{
-    ForkResult, Pid, close, dup, dup2_stderr, dup2_stdin, dup2_stdout, fork, setsid,
+    close, dup, dup2_stderr, dup2_stdin, dup2_stdout, fork, setsid, ForkResult, Pid,
 };
 use std;
 use std::fs::File;
@@ -18,7 +18,7 @@ use std::os::unix::process::CommandExt;
 use std::process::Command;
 use std::{thread, time};
 
-/// Start a process in a forked tty so you can interact with it the same as you would
+/// Start a process in a forked tty to interact with it like you would
 /// within a terminal
 ///
 /// The process and pty session are killed upon dropping `PtyProcess`
@@ -68,7 +68,7 @@ use nix::pty::ptsname_r;
 /// instead of using a static mutex this calls ioctl with TIOCPTYGNAME directly
 /// based on https://blog.tarq.io/ptsname-on-osx-with-rust/
 fn ptsname_r(fd: &PtyMaster) -> nix::Result<String> {
-    use nix::libc::{TIOCPTYGNAME, ioctl};
+    use nix::libc::{ioctl, TIOCPTYGNAME};
     use std::ffi::CStr;
 
     // the buffer size on OSX is 128, defined by sys/ttycom.h
@@ -144,17 +144,18 @@ impl PtyProcess {
         Ok(fd.into())
     }
 
-    /// At the drop of `PtyProcess` the running process is killed. This is blocking forever if
-    /// the process does not react to a normal kill. If `kill_timeout` is set the process is
-    /// `kill -9`ed after duration
+    /// At the drop of `PtyProcess` the running process is killed (blocking).
+    ///
+    /// This is blocking forever if the process does not react to a normal kill.
+    /// If `kill_timeout` is set the process is `kill -9`ed after duration.
     pub fn set_kill_timeout(&mut self, timeout_ms: Option<u64>) {
         self.kill_timeout = timeout_ms.map(time::Duration::from_millis);
     }
 
-    /// Get status of child process, non-blocking.
+    /// Get status of child process (non-blocking).
     ///
-    /// This method runs waitpid on the process.
-    /// This means: If you ran `exit()` before or `status()` this method will
+    /// This method runs waitpid on the process:
+    /// if you ran `exit()` before or `status()` this method will
     /// return `None`
     ///
     /// # Example
@@ -176,29 +177,34 @@ impl PtyProcess {
         wait::waitpid(self.child_pid, Some(wait::WaitPidFlag::WNOHANG)).ok()
     }
 
-    /// Wait until process has exited. This is a blocking call.
+    /// Wait until process has exited (non-blocking).
+    ///
     /// If the process doesn't terminate this will block forever.
     pub fn wait(&self) -> Result<wait::WaitStatus, Error> {
         wait::waitpid(self.child_pid, None).map_err(Error::from)
     }
 
-    /// Regularly exit the process, this method is blocking until the process is dead
+    /// Regularly exit the process (blocking).
+    ///
+    /// This method is blocking until the process is dead
     pub fn exit(&mut self) -> Result<wait::WaitStatus, Error> {
         self.kill(signal::SIGTERM)
     }
 
-    /// Non-blocking variant of `kill()` (doesn't wait for process to be killed)
+    /// Kill the process with a specific signal (non-blocking).
     pub fn signal(&mut self, sig: signal::Signal) -> Result<(), Error> {
         signal::kill(self.child_pid, sig).map_err(Error::from)
     }
 
-    /// Kill the process with a specific signal. This method blocks, until the process is dead
+    /// Kill the process with a specific signal (blocking).
+    ///
+    /// This method blocks until the process is dead
     ///
-    /// repeatedly sends SIGTERM to the process until it died,
+    /// This repeatedly sends SIGTERM to the process until it died,
     /// the pty session is closed upon dropping `PtyMaster`,
     /// so we don't need to explicitly do that here.
     ///
-    /// if `kill_timeout` is set and a repeated sending of signal does not result in the process
+    /// If `kill_timeout` is set and a repeated sending of signal does not result in the process
     /// being killed, then `kill -9` is sent after the `kill_timeout` duration has elapsed.
     pub fn kill(&mut self, sig: signal::Signal) -> Result<wait::WaitStatus, Error> {
         let start = time::Instant::now();

src/reader.rs

@@ -8,15 +8,14 @@ use std::sync::mpsc::{channel, Receiver};
 use std::thread;
 use std::{fmt, time};
 
-/// Options for `NBReader`
-///
-/// - timeout:
-///  + `None`: `read_until` is blocking forever. This is probably not what you want
-///  + `Some(millis)`: after millis milliseconds a timeout error is raised
-/// - `strip_ansi_escape_codes`: Whether to filter out escape codes, such as colors.
+/// Options for [`NBReader`]
 #[derive(Default)]
 pub struct Options {
+    /// `None`: `read_until` is blocking forever. This is probably not what you want
+    ///
+    /// `Some(millis)`: after millis milliseconds a timeout error is raised
     pub timeout_ms: Option<u64>,
+    /// Whether to filter out escape codes, such as colors.
     pub strip_ansi_escape_codes: bool,
 }
 
@@ -35,10 +34,10 @@ pub struct NBReader {
 impl NBReader {
     /// Create a new reader instance
     ///
-    /// # Arguments:
+    /// # Arguments
     ///
-    /// - f: file like object
-    /// - options: see `Options`
+    /// - `f`: file like object
+    /// - `options`: see [`Options`]
     pub fn new<R: Read + Send + 'static>(f: R, options: Options) -> NBReader {
         let (tx, rx) = channel();
 
@@ -87,7 +86,7 @@ impl NBReader {
         }
     }
 
-    /// reads all available chars from the read channel and stores them in self.buffer
+    /// Reads all available chars from the read channel and stores them in [`Self::buffer`]
     fn read_into_buffer(&mut self) -> Result<(), Error> {
         if self.eof {
             return Ok(());
@@ -109,24 +108,13 @@ impl NBReader {
         Ok(())
     }
 
-    /// Read until needle is found (blocking!) and return tuple with:
-    /// 1. yet unread string until and without needle
-    /// 2. matched needle
+    /// Read until needle is found (blocking!)
     ///
     /// This methods loops (while reading from the Cursor) until the needle is found.
     ///
-    /// There are different modes:
-    ///
-    /// - `ReadUntil::String` searches for string (use '\n'.`to_string()` to search for newline).
-    ///   Returns not yet read data in first String, and needle in second String
-    /// - `ReadUntil::Regex` searches for regex
-    ///   Returns not yet read data in first String and matched regex in second String
-    /// - `ReadUntil::NBytes` reads maximum n bytes
-    ///   Returns n bytes in second String, first String is left empty
-    /// - `ReadUntil::EOF` reads until end of file is reached
-    ///   Returns all bytes in second String, first is left empty
-    ///
-    /// Note that when used with a tty the lines end with \r\n
+    /// Returns a tuple with:
+    /// 1. yet unread string until and without needle
+    /// 2. matched needle
     ///
     /// Returns error if EOF is reached before the needle could be found.
     ///
@@ -193,8 +181,9 @@ impl NBReader {
         }
     }
 
-    /// Try to read one char from internal buffer. Returns None if
-    /// no char is ready, Some(char) otherwise. This is non-blocking
+    /// Try to read one char from internal buffer (non-blocking).
+    ///
+    /// Returns `None` if no char is ready `Some(char)` otherwise.
     pub fn try_read(&mut self) -> Option<char> {
         // discard eventual errors, EOF will be handled in read_until correctly
         let _ = self.read_into_buffer();
@@ -207,10 +196,24 @@ impl NBReader {
 }
 
 /// See [`NBReader::read_until`]
+///
+/// Note that when used with a tty the lines end with \r\n
 pub enum ReadUntil {
+    /// Searches for string (use '\n'.`to_string()` to search for newline).
+    ///
+    /// Returns not yet read data in first String, and needle in second String
     String(String),
+    /// `ReadUntil::Regex` searches for regex
+    ///
+    /// Returns not yet read data in first String and matched regex in second String
     Regex(Regex),
+    /// `ReadUntil::NBytes` reads maximum n bytes
+    ///
+    /// Returns n bytes in second String, first String is left empty
     NBytes(usize),
+    /// `ReadUntil::EOF` reads until end of file is reached
+    ///
+    /// Returns all bytes in second String, first is left empty
     EOF,
     Any(Vec<ReadUntil>),
 }
@@ -237,12 +240,12 @@ impl fmt::Display for ReadUntil {
     }
 }
 
-/// find first occurrence of needle within buffer
+/// Find first occurrence of needle within buffer
 ///
 /// # Arguments:
 ///
-/// - buffer: the currently read buffer from a process which will still grow in the future
-/// - eof: if the process already sent an EOF or a HUP
+/// - `buffer`: the currently read buffer from a process which will still grow in the future
+/// - `eof`: if the process already sent an EOF or a HUP
 ///
 /// # Return
 ///