tests: doc comments

src/libcore/any.rs

@@ -31,8 +31,8 @@
 //! fn log<T: Any + Debug>(value: &T) {
 //!     let value_any = value as &dyn Any;
 //!
-//!     // try to convert our value to a String.  If successful, we want to
-//!     // output the String's length as well as its value.  If not, it's a
+//!     // Try to convert our value to a `String`. If successful, we want to
+//!     // output the String`'s length as well as its value. If not, it's a
 //!     // different type: just print it out unadorned.
 //!     match value_any.downcast_ref::<String>() {
 //!         Some(as_string) => {

src/libcore/cell.rs

@@ -1174,7 +1174,7 @@ impl<'b, T: ?Sized> Ref<'b, T> {
         }
     }
 
-    /// Split a `Ref` into multiple `Ref`s for different components of the
+    /// Splits a `Ref` into multiple `Ref`s for different components of the
     /// borrowed data.
     ///
     /// The `RefCell` is already immutably borrowed, so this cannot fail.
@@ -1253,7 +1253,7 @@ impl<'b, T: ?Sized> RefMut<'b, T> {
         }
     }
 
-    /// Split a `RefMut` into multiple `RefMut`s for different components of the
+    /// Splits a `RefMut` into multiple `RefMut`s for different components of the
     /// borrowed data.
     ///
     /// The underlying `RefCell` will remain mutably borrowed until both

src/libcore/intrinsics.rs

@@ -1,6 +1,6 @@
-//! rustc compiler intrinsics.
+//! Compiler intrinsics.
 //!
-//! The corresponding definitions are in librustc_codegen_llvm/intrinsic.rs.
+//! The corresponding definitions are in `librustc_codegen_llvm/intrinsic.rs`.
 //!
 //! # Volatiles
 //!
@@ -697,7 +697,7 @@ extern "rust-intrinsic" {
     /// Creates a value initialized to zero.
     ///
     /// `init` is unsafe because it returns a zeroed-out datum,
-    /// which is unsafe unless T is `Copy`.  Also, even if T is
+    /// which is unsafe unless `T` is `Copy`. Also, even if T is
     /// `Copy`, an all-zero value may not correspond to any legitimate
     /// state for the type in question.
     pub fn init<T>() -> T;

src/libcore/num/dec2flt/mod.rs

@@ -209,7 +209,7 @@ fn pfe_invalid() -> ParseFloatError {
     ParseFloatError { kind: FloatErrorKind::Invalid }
 }
 
-/// Split decimal string into sign and the rest, without inspecting or validating the rest.
+/// Splits a decimal string into sign and the rest, without inspecting or validating the rest.
 fn extract_sign(s: &str) -> (Sign, &str) {
     match s.as_bytes()[0] {
         b'+' => (Sign::Positive, &s[1..]),

src/libcore/num/dec2flt/rawfp.rs

@@ -59,10 +59,10 @@ pub trait RawFloat
     /// Type used by `to_bits` and `from_bits`.
     type Bits: Add<Output = Self::Bits> + From<u8> + TryFrom<u64>;
 
-    /// Raw transmutation to integer.
+    /// Performs a raw transmutation to an integer.
     fn to_bits(self) -> Self::Bits;
 
-    /// Raw transmutation from integer.
+    /// Performs a raw transmutation from an integer.
     fn from_bits(v: Self::Bits) -> Self;
 
     /// Returns the category that this number falls into.
@@ -71,14 +71,14 @@ pub trait RawFloat
     /// Returns the mantissa, exponent and sign as integers.
     fn integer_decode(self) -> (u64, i16, i8);
 
-    /// Decode the float.
+    /// Decodes the float.
     fn unpack(self) -> Unpacked;
 
-    /// Cast from a small integer that can be represented exactly.  Panic if the integer can't be
+    /// Casts from a small integer that can be represented exactly. Panic if the integer can't be
     /// represented, the other code in this module makes sure to never let that happen.
     fn from_int(x: u64) -> Self;
 
-    /// Get the value 10<sup>e</sup> from a pre-computed table.
+    /// Gets the value 10<sup>e</sup> from a pre-computed table.
     /// Panics for `e >= CEIL_LOG5_OF_MAX_SIG`.
     fn short_fast_pow10(e: usize) -> Self;
 

src/libcore/slice/mod.rs

@@ -3145,7 +3145,7 @@ unsafe impl<T: Sync> Sync for Iter<'_, T> {}
 unsafe impl<T: Sync> Send for Iter<'_, T> {}
 
 impl<'a, T> Iter<'a, T> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
@@ -3247,7 +3247,7 @@ unsafe impl<T: Sync> Sync for IterMut<'_, T> {}
 unsafe impl<T: Send> Send for IterMut<'_, T> {}
 
 impl<'a, T> IterMut<'a, T> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// To avoid creating `&mut` references that alias, this is forced
     /// to consume the iterator.

src/libcore/str/mod.rs

@@ -612,7 +612,7 @@ impl<'a> DoubleEndedIterator for Chars<'a> {
 impl FusedIterator for Chars<'_> {}
 
 impl<'a> Chars<'a> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
@@ -702,7 +702,7 @@ impl<'a> DoubleEndedIterator for CharIndices<'a> {
 impl FusedIterator for CharIndices<'_> {}
 
 impl<'a> CharIndices<'a> {
-    /// View the underlying data as a subslice of the original data.
+    /// Views the underlying data as a subslice of the original data.
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
@@ -2643,7 +2643,7 @@ impl str {
         Bytes(self.as_bytes().iter().cloned())
     }
 
-    /// Split a string slice by whitespace.
+    /// Splits a string slice by whitespace.
     ///
     /// The iterator returned will return string slices that are sub-slices of
     /// the original string slice, separated by any amount of whitespace.
@@ -2686,7 +2686,7 @@ impl str {
         SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
     }
 
-    /// Split a string slice by ASCII whitespace.
+    /// Splits a string slice by ASCII whitespace.
     ///
     /// The iterator returned will return string slices that are sub-slices of
     /// the original string slice, separated by any amount of ASCII whitespace.

src/libproc_macro/bridge/scoped_cell.rs

@@ -38,7 +38,7 @@ impl<T: LambdaL> ScopedCell<T> {
         ScopedCell(Cell::new(value))
     }
 
-    /// Set the value in `self` to `replacement` while
+    /// Sets the value in `self` to `replacement` while
     /// running `f`, which gets the old value, mutably.
     /// The old value will be restored after `f` exits, even
     /// by panic, including modifications made to it by `f`.
@@ -73,7 +73,7 @@ impl<T: LambdaL> ScopedCell<T> {
         f(RefMutL(put_back_on_drop.value.as_mut().unwrap()))
     }
 
-    /// Set the value in `self` to `value` while running `f`.
+    /// Sets the value in `self` to `value` while running `f`.
     pub fn set<'a, R>(&self, value: <T as ApplyL<'a>>::Out, f: impl FnOnce() -> R) -> R {
         self.replace(value, |_| f())
     }

src/libproc_macro/diagnostic.rs

@@ -56,7 +56,7 @@ pub struct Diagnostic {
 
 macro_rules! diagnostic_child_methods {
     ($spanned:ident, $regular:ident, $level:expr) => (
-        /// Add a new child diagnostic message to `self` with the level
+        /// Adds a new child diagnostic message to `self` with the level
         /// identified by this method's name with the given `spans` and
         /// `message`.
         #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
@@ -67,7 +67,7 @@ macro_rules! diagnostic_child_methods {
             self
         }
 
-        /// Add a new child diagnostic message to `self` with the level
+        /// Adds a new child diagnostic message to `self` with the level
         /// identified by this method's name with the given `message`.
         #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
         pub fn $regular<T: Into<String>>(mut self, message: T) -> Diagnostic {
@@ -93,7 +93,7 @@ impl<'a> Iterator for Children<'a> {
 
 #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
 impl Diagnostic {
-    /// Create a new diagnostic with the given `level` and `message`.
+    /// Creates a new diagnostic with the given `level` and `message`.
     #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
     pub fn new<T: Into<String>>(level: Level, message: T) -> Diagnostic {
         Diagnostic {
@@ -104,7 +104,7 @@ impl Diagnostic {
         }
     }
 
-    /// Create a new diagnostic with the given `level` and `message` pointing to
+    /// Creates a new diagnostic with the given `level` and `message` pointing to
     /// the given set of `spans`.
     #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
     pub fn spanned<S, T>(spans: S, level: Level, message: T) -> Diagnostic

src/libproc_macro/lib.rs

@@ -88,7 +88,7 @@ impl TokenStream {
 /// or characters not existing in the language.
 /// All tokens in the parsed stream get `Span::call_site()` spans.
 ///
-/// NOTE: Some errors may cause panics instead of returning `LexError`. We reserve the right to
+/// NOTE: some errors may cause panics instead of returning `LexError`. We reserve the right to
 /// change these errors into `LexError`s later.
 #[stable(feature = "proc_macro_lib", since = "1.15.0")]
 impl FromStr for TokenStream {
@@ -244,7 +244,7 @@ impl !Sync for Span {}
 
 macro_rules! diagnostic_method {
     ($name:ident, $level:expr) => (
-        /// Create a new `Diagnostic` with the given `message` at the span
+        /// Creates a new `Diagnostic` with the given `message` at the span
         /// `self`.
         #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
         pub fn $name<T: Into<String>>(self, message: T) -> Diagnostic {
@@ -290,19 +290,19 @@ impl Span {
         Span(self.0.source())
     }
 
-    /// Get the starting line/column in the source file for this span.
+    /// Gets the starting line/column in the source file for this span.
     #[unstable(feature = "proc_macro_span", issue = "54725")]
     pub fn start(&self) -> LineColumn {
         self.0.start()
     }
 
-    /// Get the ending line/column in the source file for this span.
+    /// Gets the ending line/column in the source file for this span.
     #[unstable(feature = "proc_macro_span", issue = "54725")]
     pub fn end(&self) -> LineColumn {
         self.0.end()
     }
 
-    /// Create a new span encompassing `self` and `other`.
+    /// Creates a new span encompassing `self` and `other`.
     ///
     /// Returns `None` if `self` and `other` are from different files.
     #[unstable(feature = "proc_macro_span", issue = "54725")]
@@ -368,7 +368,7 @@ impl !Sync for LineColumn {}
 pub struct SourceFile(bridge::client::SourceFile);
 
 impl SourceFile {
-    /// Get the path to this source file.
+    /// Gets the path to this source file.
     ///
     /// ### Note
     /// If the code span associated with this `SourceFile` was generated by an external macro, this

src/libstd/sync/mpsc/select.rs

@@ -76,7 +76,7 @@ impl !marker::Send for Select {}
 /// interact with the underlying receiver.
 pub struct Handle<'rx, T:Send+'rx> {
     /// The ID of this handle, used to compare against the return value of
-    /// `Select::wait()`
+    /// `Select::wait()`.
     id: usize,
     selector: *mut SelectInner,
     next: *mut Handle<'static, ()>,

src/test/incremental/change_add_field/struct_point.rs

@@ -60,7 +60,7 @@ pub mod point {
     }
 }
 
-/// A fn that has the changed type in its signature; must currently be
+/// A function that has the changed type in its signature; must currently be
 /// rebuilt.
 ///
 /// You could imagine that, in the future, if the change were
@@ -76,7 +76,7 @@ pub mod fn_with_type_in_sig {
     }
 }
 
-/// Call a fn that has the changed type in its signature; this
+/// Call a function that has the changed type in its signature; this
 /// currently must also be rebuilt.
 ///
 /// You could imagine that, in the future, if the change were
@@ -92,7 +92,7 @@ pub mod call_fn_with_type_in_sig {
     }
 }
 
-/// A fn that uses the changed type, but only in its body, not its
+/// A function that uses the changed type, but only in its body, not its
 /// signature.
 ///
 /// You could imagine that, in the future, if the change were
@@ -108,10 +108,10 @@ pub mod fn_with_type_in_body {
     }
 }
 
-/// A fn X that calls a fn Y, where Y uses the changed type in its
+/// A function `X` that calls a function `Y`, where `Y` uses the changed type in its
 /// body. In this case, the effects of the change should be contained
-/// to Y; X should not have to be rebuilt, nor should it need to be
-/// typechecked again.
+/// to `Y`; `X` should not have to be rebuilt, nor should it need to be
+/// type-checked again.
 pub mod call_fn_with_type_in_body {
     use fn_with_type_in_body;
 
@@ -121,7 +121,7 @@ pub mod call_fn_with_type_in_body {
     }
 }
 
-/// A fn item that makes an instance of `Point` but does not invoke methods
+/// A function item that makes an instance of `Point` but does not invoke methods.
 pub mod fn_make_struct {
     use point::Point;
 
@@ -131,7 +131,7 @@ pub mod fn_make_struct {
     }
 }
 
-/// A fn item that reads fields from `Point` but does not invoke methods
+/// A function item that reads fields from `Point` but does not invoke methods.
 pub mod fn_read_field {
     use point::Point;
 
@@ -141,7 +141,7 @@ pub mod fn_read_field {
     }
 }
 
-/// A fn item that writes to a field of `Point` but does not invoke methods
+/// A function item that writes to a field of `Point` but does not invoke methods.
 pub mod fn_write_field {
     use point::Point;
 

src/test/run-pass/auxiliary/svh-b.rs

@@ -1,7 +1,7 @@
-//! This is a client of the `a` crate defined in "svn-a-base.rs".  The
-//! rpass and cfail tests (such as "run-pass/svh-add-comment.rs") use
+//! This is a client of the `a` crate defined in `svn-a-base.rs`. The
+//! rpass and cfail tests (such as `run-pass/svh-add-comment.rs`) use
 //! it by swapping in a different object code library crate built from
-//! some variant of "svn-a-base.rs", and then we are checking if the
+//! some variant of `svn-a-base.rs`, and then we are checking if the
 //! compiler properly ignores or accepts the change, based on whether
 //! the change could affect the downstream crate content or not
 //! (#14132).

src/test/run-pass/issues/issue-7012.rs

@@ -5,7 +5,7 @@
 /*
 # Comparison of static arrays
 
-The expected behaviour would be that test==test1, therefore 'true'
+The expected behaviour would be that `test == test1`, therefore 'true'
 would be printed, however the below prints false.
 */
 

src/test/run-pass/item-attributes.rs

@@ -163,7 +163,7 @@ mod test_foreign_items {
 }
 
 
-// FIXME #623 - these aren't supported yet
+// FIXME(#623): - these aren't supported yet
 /*mod test_literals {
     #![str = "s"]
     #![char = 'c']

src/test/run-pass/monomorphize-abi-alignment.rs

@@ -2,7 +2,7 @@
 /*!
  * On x86_64-linux-gnu and possibly other platforms, structs get 8-byte "preferred" alignment,
  * but their "ABI" alignment (i.e., what actually matters for data layout) is the largest alignment
- * of any field.  (Also, u64 has 8-byte ABI alignment; this is not always true).
+ * of any field. (Also, `u64` has 8-byte ABI alignment; this is not always true).
  *
  * On such platforms, if monomorphize uses the "preferred" alignment, then it will unify
  * `A` and `B`, even though `S<A>` and `S<B>` have the field `t` at different offsets,

src/test/run-pass/numbers-arithmetic/num-wrapping.rs

@@ -175,7 +175,7 @@ fn test_op_assigns() {
                 assert_eq!(black_box(tmp), Wrapping($ans));
             }
 
-            // FIXME(30524): Uncomment this test
+            // FIXME(30524): uncomment this test
             /*
             {
                 let mut tmp = Wrapping($initial);

src/test/rustdoc/issue-27862.rs

@@ -1,4 +1,4 @@
-/// Test  | Table
+/// Tests  | Table
 /// ------|-------------
 /// t = b | id = \|x\| x
 pub struct Foo; // @has issue_27862/struct.Foo.html //td 'id = |x| x'

src/test/ui/associated-types/associated-types-coherence-failure.rs

@@ -41,7 +41,7 @@ impl ToOwned for u8 {
 pub trait ToOwned {
     type Owned;
 
-    /// Create owned data from borrowed data, usually by copying.
+    /// Creates owned data from borrowed data, usually by copying.
     fn to_owned(&self) -> Self::Owned;
 }
 

src/test/ui/issues/issue-20797.rs

@@ -17,7 +17,7 @@ impl PathExtensions for PathBuf {}
 /// A strategy for acquiring more subpaths to walk.
 pub trait Strategy {
     type P: PathExtensions;
-    /// Get additional subpaths from a given path.
+    /// Gets additional subpaths from a given path.
     fn get_more(&self, item: &Self::P) -> io::Result<Vec<Self::P>>;
     /// Determine whether a path should be walked further.
     /// This is run against each item from `get_more()`.
@@ -44,7 +44,7 @@ pub struct Subpaths<S: Strategy> {
 }
 
 impl<S: Strategy> Subpaths<S> {
-    /// Create a directory walker with a root path and strategy.
+    /// Creates a directory walker with a root path and strategy.
     pub fn new(p: &S::P, strategy: S) -> io::Result<Subpaths<S>> {
         let stack = strategy.get_more(p)?;
         Ok(Subpaths { stack: stack, strategy: strategy })
@@ -52,7 +52,7 @@ impl<S: Strategy> Subpaths<S> {
 }
 
 impl<S: Default + Strategy> Subpaths<S> {
-    /// Create a directory walker with a root path and a default strategy.
+    /// Creates a directory walker with a root path and a default strategy.
     pub fn walk(p: &S::P) -> io::Result<Subpaths<S>> {
         Subpaths::new(p, Default::default())
     }

src/test/ui/issues/issue-48636.fixed

@@ -4,7 +4,7 @@
 
 struct S {
     x: u8,
-    /// The id of the parent core
+    /// The ID of the parent core
     y: u8,
 }
 //~^^^ ERROR found a documentation comment that doesn't document anything

src/test/ui/issues/issue-48636.rs

@@ -4,7 +4,7 @@
 
 struct S {
     x: u8
-    /// The id of the parent core
+    /// The ID of the parent core
     y: u8,
 }
 //~^^^ ERROR found a documentation comment that doesn't document anything

src/test/ui/issues/issue-52126-assign-op-invariance.rs

@@ -27,7 +27,7 @@ impl<'l> AddAssign for Counter<'l>
     }
 }
 
-/// often times crashes, if not prints invalid strings
+/// Often crashes, if not prints invalid strings.
 pub fn panics() {
     let mut acc = Counter{map: HashMap::new()};
     for line in vec!["123456789".to_string(), "12345678".to_string()] {

src/test/ui/nll/user-annotations/issue-55241.rs

@@ -18,7 +18,7 @@ pub trait NodeCodec<H: Hasher> {
 }
 
 pub trait Trie<H: Hasher, C: NodeCodec<H>> {
-    /// Return the root of the trie.
+    /// Returns the root of the trie.
     fn root(&self) -> &H::Out;
 
     /// Is the trie empty?

src/test/ui/on-unimplemented/bad-annotation.rs

@@ -10,7 +10,7 @@ trait Foo<Bar, Baz, Quux>
 
 #[rustc_on_unimplemented="a collection of type `{Self}` cannot be built from an iterator over elements of type `{A}`"]
 trait MyFromIterator<A> {
-    /// Build a container with elements from an external iterator.
+    /// Builds a container with elements from an external iterator.
     fn my_from_iter<T: Iterator<Item=A>>(iterator: T) -> Self;
 }
 

src/test/ui/on-unimplemented/on-trait.rs

@@ -15,7 +15,7 @@ fn foobar<U: Clone, T: Foo<u8, U, u32>>() -> T {
 
 #[rustc_on_unimplemented="a collection of type `{Self}` cannot be built from an iterator over elements of type `{A}`"]
 trait MyFromIterator<A> {
-    /// Build a container with elements from an external iterator.
+    /// Builds a container with elements from an external iterator.
     fn my_from_iter<T: Iterator<Item=A>>(iterator: T) -> Self;
 }
 

src/test/ui/svh/auxiliary/svh-b.rs

@@ -1,7 +1,7 @@
-//! This is a client of the `a` crate defined in "svn-a-base.rs".  The
-//! rpass and cfail tests (such as "run-pass/svh-add-comment.rs") use
+//! This is a client of the `a` crate defined in `svn-a-base.rs`. The
+//! rpass and cfail tests (such as `run-pass/svh-add-comment.rs`) use
 //! it by swapping in a different object code library crate built from
-//! some variant of "svn-a-base.rs", and then we are checking if the
+//! some variant of `svn-a-base.rs`, and then we are checking if the
 //! compiler properly ignores or accepts the change, based on whether
 //! the change could affect the downstream crate content or not
 //! (#14132).