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!

src/common.rs

@@ -113,31 +113,31 @@ impl CompareMode {
 
 #[derive(Clone)]
 pub struct Config {
-    /// Whether to overwrite stderr/stdout files instead of complaining about changes in output
+    /// `true` to to overwrite stderr/stdout files instead of complaining about changes in output.
     pub bless: bool,
 
-    /// The library paths required for running the compiler
+    /// The library paths required for running the compiler.
     pub compile_lib_path: PathBuf,
 
-    /// The library paths required for running compiled programs
+    /// The library paths required for running compiled programs.
     pub run_lib_path: PathBuf,
 
-    /// The rustc executable
+    /// The rustc executable.
     pub rustc_path: PathBuf,
 
-    /// The rustdoc executable
+    /// The rustdoc executable.
     pub rustdoc_path: Option<PathBuf>,
 
-    /// The python executable to use for LLDB
+    /// The Python executable to use for LLDB.
     pub lldb_python: String,
 
-    /// The python executable to use for htmldocck
+    /// The Python executable to use for htmldocck.
     pub docck_python: String,
 
-    /// The llvm FileCheck binary path
+    /// The LLVM `FileCheck` binary path.
     pub llvm_filecheck: Option<PathBuf>,
 
-    /// The valgrind path
+    /// The valgrind path.
     pub valgrind_path: Option<String>,
 
     /// Whether to fail if we can't run run-pass-valgrind tests under valgrind
@@ -305,15 +305,15 @@ pub fn output_testname_unique(
 }
 
 /// Absolute path to the directory where all output for the given
-/// test/revision should reside.  Example:
+/// test/revision should reside. Example:
 ///   /path/to/build/host-triple/test/ui/relative/testname.revision.mode/
 pub fn output_base_dir(config: &Config, testpaths: &TestPaths, revision: Option<&str>) -> PathBuf {
     output_relative_path(config, &testpaths.relative_dir)
         .join(output_testname_unique(config, testpaths, revision))
 }
 
 /// Absolute path to the base filename used as output for the given
-/// test/revision.  Example:
+/// test/revision. Example:
 ///   /path/to/build/host-triple/test/ui/relative/testname.revision.mode/testname
 pub fn output_base_name(config: &Config, testpaths: &TestPaths, revision: Option<&str>) -> PathBuf {
     output_base_dir(config, testpaths, revision).join(testpaths.file.file_stem().unwrap())

src/header.rs

@@ -12,7 +12,7 @@ use crate::extract_gdb_version;
 /// Whether to ignore the test.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub enum Ignore {
-    /// Run it.
+    /// Runs it.
     Run,
     /// Ignore it totally.
     Ignore,
@@ -389,7 +389,7 @@ impl TestProps {
         props
     }
 
-    /// Load properties from `testfile` into `props`. If a property is
+    /// Loads properties from `testfile` into `props`. If a property is
     /// tied to a particular revision `foo` (indicated by writing
     /// `//[foo]`), then the property is ignored unless `cfg` is
     /// `Some("foo")`.

src/main.rs

@@ -808,7 +808,7 @@ fn make_test_closure(
     }))
 }
 
-/// Returns true if the given target is an Android target for the
+/// Returns `true` if the given target is an Android target for the
 /// purposes of GDB testing.
 fn is_android_gdb_target(target: &String) -> bool {
     match &target[..] {

src/runtest.rs

@@ -1379,7 +1379,7 @@ impl<'test> TestCx<'test> {
         }
     }
 
-    /// Returns true if we should report an error about `actual_error`,
+    /// Returns `true` if we should report an error about `actual_error`,
     /// which did not match any of the expected error. We always require
     /// errors/warnings to be explicitly listed, but only require
     /// helps/notes if there are explicit helps/notes given.
@@ -1974,14 +1974,14 @@ impl<'test> TestCx<'test> {
         fs::write(&outfile, out).unwrap();
     }
 
-    /// Create a filename for output with the given extension.  Example:
-    ///   /.../testname.revision.mode/testname.extension
+    /// Creates a filename for output with the given extension.
+    /// E.g., `/.../testname.revision.mode/testname.extension`.
     fn make_out_name(&self, extension: &str) -> PathBuf {
         self.output_base_name().with_extension(extension)
     }
 
-    /// Directory where auxiliary files are written.  Example:
-    ///   /.../testname.revision.mode/auxiliary/
+    /// Gets the directory where auxiliary files are written.
+    /// E.g., `/.../testname.revision.mode/auxiliary/`.
     fn aux_output_dir_name(&self) -> PathBuf {
         self.output_base_dir()
             .join("auxiliary")
@@ -1993,7 +1993,7 @@ impl<'test> TestCx<'test> {
         output_testname_unique(self.config, self.testpaths, self.safe_revision())
     }
 
-    /// The revision, ignored for Incremental since it wants all revisions in
+    /// The revision, ignored for incremental compilation since it wants all revisions in
     /// the same directory.
     fn safe_revision(&self) -> Option<&str> {
         if self.config.mode == Incremental {
@@ -2003,16 +2003,16 @@ impl<'test> TestCx<'test> {
         }
     }
 
-    /// Absolute path to the directory where all output for the given
-    /// test/revision should reside.  Example:
-    ///   /path/to/build/host-triple/test/ui/relative/testname.revision.mode/
+    /// Gets the absolute path to the directory where all output for the given
+    /// test/revision should reside.
+    /// E.g., `/path/to/build/host-triple/test/ui/relative/testname.revision.mode/`.
     fn output_base_dir(&self) -> PathBuf {
         output_base_dir(self.config, self.testpaths, self.safe_revision())
     }
 
-    /// Absolute path to the base filename used as output for the given
-    /// test/revision.  Example:
-    ///   /.../relative/testname.revision.mode/testname
+    /// Gets the absolute path to the base filename used as output for the given
+    /// test/revision.
+    /// E.g., `/.../relative/testname.revision.mode/testname`.
     fn output_base_name(&self) -> PathBuf {
         output_base_name(self.config, self.testpaths, self.safe_revision())
     }