Auto merge of #58341 - alexreg:cosmetic-2-doc-comments, r=steveklabnik

Cosmetic improvements to doc comments

This has been factored out from rust-lang/rust#58036 to only include changes to documentation comments (throughout the rustc codebase).

r? @steveklabnik

Once you're happy with this, maybe we could get it through with r=1, so it doesn't constantly get invalidated? (I'm not sure this will be an issue, but just in case...) Anyway, thanks for your advice so far!

lib.rs

@@ -60,14 +60,14 @@ pub type StdoutTerminal = dyn Terminal<Output = Stdout> + Send;
 pub type StderrTerminal = dyn Terminal<Output = Stderr> + Send;
 
 #[cfg(not(windows))]
-/// Return a Terminal wrapping stdout, or None if a terminal couldn't be
+/// Returns a Terminal wrapping stdout, or None if a terminal couldn't be
 /// opened.
 pub fn stdout() -> Option<Box<StdoutTerminal>> {
     TerminfoTerminal::new(io::stdout()).map(|t| Box::new(t) as Box<StdoutTerminal>)
 }
 
 #[cfg(windows)]
-/// Return a Terminal wrapping stdout, or None if a terminal couldn't be
+/// Returns a Terminal wrapping stdout, or None if a terminal couldn't be
 /// opened.
 pub fn stdout() -> Option<Box<StdoutTerminal>> {
     TerminfoTerminal::new(io::stdout())
@@ -76,14 +76,14 @@ pub fn stdout() -> Option<Box<StdoutTerminal>> {
 }
 
 #[cfg(not(windows))]
-/// Return a Terminal wrapping stderr, or None if a terminal couldn't be
+/// Returns a Terminal wrapping stderr, or None if a terminal couldn't be
 /// opened.
 pub fn stderr() -> Option<Box<StderrTerminal>> {
     TerminfoTerminal::new(io::stderr()).map(|t| Box::new(t) as Box<StderrTerminal>)
 }
 
 #[cfg(windows)]
-/// Return a Terminal wrapping stderr, or None if a terminal couldn't be
+/// Returns a Terminal wrapping stderr, or None if a terminal couldn't be
 /// opened.
 pub fn stderr() -> Option<Box<StderrTerminal>> {
     TerminfoTerminal::new(io::stderr())
@@ -170,12 +170,12 @@ pub trait Terminal: Write {
     /// if there was an I/O error.
     fn bg(&mut self, color: color::Color) -> io::Result<bool>;
 
-    /// Sets the given terminal attribute, if supported.  Returns `Ok(true)`
+    /// Sets the given terminal attribute, if supported. Returns `Ok(true)`
     /// if the attribute was supported, `Ok(false)` otherwise, and `Err(e)` if
     /// there was an I/O error.
     fn attr(&mut self, attr: Attr) -> io::Result<bool>;
 
-    /// Returns whether the given terminal attribute is supported.
+    /// Returns `true` if the given terminal attribute is supported.
     fn supports_attr(&self, attr: Attr) -> bool;
 
     /// Resets all terminal attributes and colors to their defaults.

terminfo/mod.rs

@@ -67,7 +67,7 @@ impl fmt::Display for Error {
 }
 
 impl TermInfo {
-    /// Create a TermInfo based on current environment.
+    /// Creates a TermInfo based on current environment.
     pub fn from_env() -> Result<TermInfo, Error> {
         let term = match env::var("TERM") {
             Ok(name) => TermInfo::from_name(&name),
@@ -82,7 +82,7 @@ impl TermInfo {
         }
     }
 
-    /// Create a TermInfo for the named terminal.
+    /// Creates a TermInfo for the named terminal.
     pub fn from_name(name: &str) -> Result<TermInfo, Error> {
         get_dbpath_for_term(name)
             .ok_or_else(|| {
@@ -209,7 +209,7 @@ impl<T: Write + Send> Terminal for TerminfoTerminal<T> {
 }
 
 impl<T: Write + Send> TerminfoTerminal<T> {
-    /// Create a new TerminfoTerminal with the given TermInfo and Write.
+    /// Creates a new TerminfoTerminal with the given TermInfo and Write.
     pub fn new_with_terminfo(out: T, terminfo: TermInfo) -> TerminfoTerminal<T> {
         let nc = if terminfo.strings.contains_key("setaf") &&
                     terminfo.strings.contains_key("setab") {
@@ -225,7 +225,7 @@ impl<T: Write + Send> TerminfoTerminal<T> {
         }
     }
 
-    /// Create a new TerminfoTerminal for the current environment with the given Write.
+    /// Creates a new TerminfoTerminal for the current environment with the given Write.
     ///
     /// Returns `None` when the terminfo cannot be found or parsed.
     pub fn new(out: T) -> Option<TerminfoTerminal<T>> {

terminfo/parm.rs

@@ -46,7 +46,7 @@ pub struct Variables {
 }
 
 impl Variables {
-    /// Return a new zero-initialized Variables
+    /// Returns a new zero-initialized Variables
     pub fn new() -> Variables {
         Variables {
             sta_va: [

terminfo/parser/compiled.rs

@@ -313,7 +313,7 @@ pub fn parse(file: &mut dyn io::Read, longnames: bool) -> Result<TermInfo, Strin
     })
 }
 
-/// Create a dummy TermInfo struct for msys terminals
+/// Creates a dummy TermInfo struct for msys terminals
 pub fn msys_terminfo() -> TermInfo {
     let mut strings = HashMap::new();
     strings.insert("sgr0".to_string(), b"\x1B[0m".to_vec());

terminfo/searcher.rs

@@ -1,4 +1,4 @@
-//! ncurses-compatible database discovery
+//! ncurses-compatible database discovery.
 //!
 //! Does not support hashed database, only filesystem!
 

win.rs

@@ -11,7 +11,7 @@ use crate::Attr;
 use crate::color;
 use crate::Terminal;
 
-/// A Terminal implementation which uses the Win32 Console API.
+/// A Terminal implementation that uses the Win32 Console API.
 pub struct WinConsole<T> {
     buf: T,
     def_foreground: color::Color,
@@ -103,8 +103,7 @@ impl<T: Write + Send + 'static> WinConsole<T> {
         }
     }
 
-    /// Returns `None` whenever the terminal cannot be created for some
-    /// reason.
+    /// Returns `None` whenever the terminal cannot be created for some reason.
     pub fn new(out: T) -> io::Result<WinConsole<T>> {
         let fg;
         let bg;