tools: doc comments

Author: Alexander Regueiro

src/tools/compiletest/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/tools/compiletest/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/tools/compiletest/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/tools/compiletest/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())
     }

src/tools/error_index_generator/main.rs

@@ -194,7 +194,7 @@ impl Formatter for MarkdownFormatter {
     }
 }
 
-/// Load all the metadata files from `metadata_dir` into an in-memory map.
+/// Loads all the metadata files from `metadata_dir` into an in-memory map.
 fn load_all_errors(metadata_dir: &Path) -> Result<ErrorMetadataMap, Box<dyn Error>> {
     let mut all_errors = BTreeMap::new();
 

src/tools/tidy/src/style.rs

@@ -44,7 +44,7 @@ enum LIUState {
     EXP_END,
 }
 
-/// Returns whether `line` appears to be a line comment containing an URL,
+/// Returns `true` if `line` appears to be a line comment containing an URL,
 /// possibly with a Markdown link label in front, and nothing else.
 /// The Markdown link label, if present, may not contain whitespace.
 /// Lines of this form are allowed to be overlength, because Markdown
@@ -79,7 +79,7 @@ fn line_is_url(line: &str) -> bool {
     state == EXP_END
 }
 
-/// Returns whether `line` is allowed to be longer than the normal limit.
+/// Returns `true` if `line` is allowed to be longer than the normal limit.
 /// Currently there is only one exception, for long URLs, but more
 /// may be added in the future.
 fn long_line_is_ok(line: &str) -> bool {

src/tools/tidy/src/unstable_book.rs

@@ -56,7 +56,7 @@ pub fn collect_unstable_book_section_file_names(dir: &path::Path) -> BTreeSet<St
         .collect()
 }
 
-/// Retrieve file names of all library feature sections in the Unstable Book with:
+/// Retrieves file names of all library feature sections in the Unstable Book with:
 ///
 /// * hyphens replaced by underscores,
 /// * the markdown suffix ('.md') removed.