diff --git a/src/bootstrap/builder.rs b/src/bootstrap/builder.rs index f512e1d7a0c62..78ba1d376be79 100644 --- a/src/bootstrap/builder.rs +++ b/src/bootstrap/builder.rs @@ -60,17 +60,17 @@ pub trait Step: 'static + Clone + Debug + PartialEq + Eq + Hash { /// Run this rule for all hosts without cross compiling. const ONLY_HOSTS: bool = false; - /// Primary function to execute this rule. Can call `builder.ensure(...)` + /// Primary function to execute this rule. Can call `builder.ensure()` /// with other steps to run those. fn run(self, builder: &Builder) -> Self::Output; /// When bootstrap is passed a set of paths, this controls whether this rule /// will execute. However, it does not get called in a "default" context - /// when we are not passed any paths; in that case, make_run is called + /// when we are not passed any paths; in that case, `make_run` is called /// directly. fn should_run(run: ShouldRun) -> ShouldRun; - /// Build up a "root" rule, either as a default rule or from a path passed + /// Builds up a "root" rule, either as a default rule or from a path passed /// to us. /// /// When path is `None`, we are executing in a context where no paths were @@ -648,7 +648,7 @@ impl<'a> Builder<'a> { add_lib_path(vec![self.rustc_libdir(compiler)], cmd); } - /// Get a path to the compiler specified. + /// Gets a path to the compiler specified. pub fn rustc(&self, compiler: Compiler) -> PathBuf { if compiler.is_snapshot(self) { self.initial_rustc.clone() @@ -659,7 +659,7 @@ impl<'a> Builder<'a> { } } - /// Get the paths to all of the compiler's codegen backends. + /// Gets the paths to all of the compiler's codegen backends. fn codegen_backends(&self, compiler: Compiler) -> impl Iterator { fs::read_dir(self.sysroot_codegen_backends(compiler)) .into_iter() diff --git a/src/bootstrap/cache.rs b/src/bootstrap/cache.rs index ea8bc657a57aa..5f84816789a68 100644 --- a/src/bootstrap/cache.rs +++ b/src/bootstrap/cache.rs @@ -227,10 +227,10 @@ lazy_static! { pub static ref INTERNER: Interner = Interner::default(); } -/// This is essentially a HashMap which allows storing any type in its input and +/// This is essentially a `HashMap` which allows storing any type in its input and /// any type in its output. It is a write-once cache; values are never evicted, /// which means that references to the value can safely be returned from the -/// get() method. +/// `get()` method. #[derive(Debug)] pub struct Cache( RefCell String { let mut features = "panic-unwind".to_string(); @@ -521,7 +521,7 @@ impl Build { features } - /// Get the space-separated set of activated features for the compiler. + /// Gets the space-separated set of activated features for the compiler. fn rustc_features(&self) -> String { let mut features = String::new(); if self.config.jemalloc { @@ -609,7 +609,7 @@ impl Build { self.out.join(&*target).join("crate-docs") } - /// Returns true if no custom `llvm-config` is set for the specified target. + /// Returns `true` if no custom `llvm-config` is set for the specified target. /// /// If no custom `llvm-config` was specified then Rust's llvm will be used. fn is_rust_llvm(&self, target: Interned) -> bool { @@ -857,13 +857,13 @@ impl Build { .map(|p| &**p) } - /// Returns true if this is a no-std `target`, if defined + /// Returns `true` if this is a no-std `target`, if defined fn no_std(&self, target: Interned) -> Option { self.config.target_config.get(&target) .map(|t| t.no_std) } - /// Returns whether the target will be tested using the `remote-test-client` + /// Returns `true` if the target will be tested using the `remote-test-client` /// and `remote-test-server` binaries. fn remote_tested(&self, target: Interned) -> bool { self.qemu_rootfs(target).is_some() || target.contains("android") || @@ -1059,7 +1059,7 @@ impl Build { self.rust_info.version(self, channel::CFG_RELEASE_NUM) } - /// Return the full commit hash + /// Returns the full commit hash. fn rust_sha(&self) -> Option<&str> { self.rust_info.sha() } @@ -1079,7 +1079,7 @@ impl Build { panic!("failed to find version in {}'s Cargo.toml", package) } - /// Returns whether unstable features should be enabled for the compiler + /// Returns `true` if unstable features should be enabled for the compiler /// we're building. fn unstable_features(&self) -> bool { match &self.config.channel[..] { @@ -1327,7 +1327,7 @@ impl<'a> Compiler { self } - /// Returns whether this is a snapshot compiler for `build`'s configuration + /// Returns `true` if this is a snapshot compiler for `build`'s configuration pub fn is_snapshot(&self, build: &Build) -> bool { self.stage == 0 && self.host == build.build } diff --git a/src/bootstrap/test.rs b/src/bootstrap/test.rs index bb00f6f625130..a882550f734f4 100644 --- a/src/bootstrap/test.rs +++ b/src/bootstrap/test.rs @@ -30,9 +30,9 @@ const ADB_TEST_DIR: &str = "/data/tmp/work"; /// The two modes of the test runner; tests or benchmarks. #[derive(Debug, PartialEq, Eq, Hash, Copy, Clone, PartialOrd, Ord)] pub enum TestKind { - /// Run `cargo test` + /// Run `cargo test`. Test, - /// Run `cargo bench` + /// Run `cargo bench`. Bench, } @@ -1288,7 +1288,7 @@ impl Step for DocTest { run.never() } - /// Run `rustdoc --test` for all documentation in `src/doc`. + /// Runs `rustdoc --test` for all documentation in `src/doc`. /// /// This will run all tests in our markdown documentation (e.g., the book) /// located in `src/doc`. The `rustdoc` that's run is the one that sits next to @@ -1408,7 +1408,7 @@ impl Step for ErrorIndex { }); } - /// Run the error index generator tool to execute the tests located in the error + /// Runs the error index generator tool to execute the tests located in the error /// index. /// /// The `error_index_generator` tool lives in `src/tools` and is used to @@ -1614,7 +1614,7 @@ impl Step for Crate { } } - /// Run all unit tests plus documentation tests for a given crate defined + /// Runs all unit tests plus documentation tests for a given crate defined /// by a `Cargo.toml` (single manifest) /// /// This is what runs tests for crates like the standard library, compiler, etc. @@ -1833,7 +1833,7 @@ fn envify(s: &str) -> String { /// the standard library and such to the emulator ahead of time. This step /// represents this and is a dependency of all test suites. /// -/// Most of the time this is a noop. For some steps such as shipping data to +/// Most of the time this is a no-op. For some steps such as shipping data to /// QEMU we have to build our own tools so we've got conditional dependencies /// on those programs as well. Note that the remote test client is built for /// the build target (us) and the server is built for the target. @@ -1904,7 +1904,7 @@ impl Step for Distcheck { run.builder.ensure(Distcheck); } - /// Run "distcheck", a 'make check' from a tarball + /// Runs "distcheck", a 'make check' from a tarball fn run(self, builder: &Builder) { builder.info("Distcheck"); let dir = builder.out.join("tmp").join("distcheck"); @@ -1965,7 +1965,7 @@ impl Step for Bootstrap { const DEFAULT: bool = true; const ONLY_HOSTS: bool = true; - /// Test the build system itself + /// Tests the build system itself. fn run(self, builder: &Builder) { let mut cmd = Command::new(&builder.initial_cargo); cmd.arg("test") diff --git a/src/bootstrap/tool.rs b/src/bootstrap/tool.rs index cd3afc59e560c..c09e9332895d8 100644 --- a/src/bootstrap/tool.rs +++ b/src/bootstrap/tool.rs @@ -40,7 +40,7 @@ impl Step for ToolBuild { run.never() } - /// Build a tool in `src/tools` + /// Builds a tool in `src/tools` /// /// This will build the specified tool with the specified `host` compiler in /// `stage` into the normal cargo output directory. @@ -621,7 +621,7 @@ tool_extended!((self, builder), ); impl<'a> Builder<'a> { - /// Get a `Command` which is ready to run `tool` in `stage` built for + /// Gets a `Command` which is ready to run `tool` in `stage` built for /// `host`. pub fn tool_cmd(&self, tool: Tool) -> Command { let mut cmd = Command::new(self.tool_exe(tool)); diff --git a/src/bootstrap/util.rs b/src/bootstrap/util.rs index 37c6c040da8e8..29aa98971fb56 100644 --- a/src/bootstrap/util.rs +++ b/src/bootstrap/util.rs @@ -33,7 +33,7 @@ pub fn exe(name: &str, target: &str) -> String { } } -/// Returns whether the file name given looks like a dynamic library. +/// Returns `true` if the file name given looks like a dynamic library. pub fn is_dylib(name: &str) -> bool { name.ends_with(".dylib") || name.ends_with(".so") || name.ends_with(".dll") } diff --git a/src/build_helper/lib.rs b/src/build_helper/lib.rs index 93aa91768121c..bd99dc118e66a 100644 --- a/src/build_helper/lib.rs +++ b/src/build_helper/lib.rs @@ -163,7 +163,7 @@ pub fn mtime(path: &Path) -> SystemTime { .unwrap_or(UNIX_EPOCH) } -/// Returns whether `dst` is up to date given that the file or files in `src` +/// Returns `true` if `dst` is up to date given that the file or files in `src` /// are used to generate it. /// /// Uses last-modified time checks to verify this. @@ -190,12 +190,12 @@ pub struct NativeLibBoilerplate { } impl NativeLibBoilerplate { - /// On OSX we don't want to ship the exact filename that compiler-rt builds. + /// On macOS we don't want to ship the exact filename that compiler-rt builds. /// This conflicts with the system and ours is likely a wildly different /// version, so they can't be substituted. /// /// As a result, we rename it here but we need to also use - /// `install_name_tool` on OSX to rename the commands listed inside of it to + /// `install_name_tool` on macOS to rename the commands listed inside of it to /// ensure it's linked against correctly. pub fn fixup_sanitizer_lib_name(&self, sanitizer_name: &str) { if env::var("TARGET").unwrap() != "x86_64-apple-darwin" { diff --git a/src/liballoc/borrow.rs b/src/liballoc/borrow.rs index 270f48e80835a..40c71f12cd8a6 100644 --- a/src/liballoc/borrow.rs +++ b/src/liballoc/borrow.rs @@ -137,11 +137,11 @@ impl ToOwned for T /// ``` /// use std::borrow::{Cow, ToOwned}; /// -/// struct Items<'a, X: 'a> where [X]: ToOwned> { +/// struct Items<'a, X: 'a> where [X]: ToOwned> { /// values: Cow<'a, [X]>, /// } /// -/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned> { +/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned> { /// fn new(v: Cow<'a, [X]>) -> Self { /// Items { values: v } /// } diff --git a/src/liballoc/collections/binary_heap.rs b/src/liballoc/collections/binary_heap.rs index 6214e1ce24587..3b94379b58f8f 100644 --- a/src/liballoc/collections/binary_heap.rs +++ b/src/liballoc/collections/binary_heap.rs @@ -863,7 +863,7 @@ struct Hole<'a, T: 'a> { } impl<'a, T> Hole<'a, T> { - /// Create a new Hole at index `pos`. + /// Create a new `Hole` at index `pos`. /// /// Unsafe because pos must be within the data slice. #[inline] diff --git a/src/liballoc/collections/btree/map.rs b/src/liballoc/collections/btree/map.rs index aaaa419dcb849..5ec5064b73515 100644 --- a/src/liballoc/collections/btree/map.rs +++ b/src/liballoc/collections/btree/map.rs @@ -2368,7 +2368,7 @@ impl<'a, K: Ord, V> OccupiedEntry<'a, K, V> { /// Gets a mutable reference to the value in the entry. /// - /// If you need a reference to the `OccupiedEntry` which may outlive the + /// If you need a reference to the `OccupiedEntry` that may outlive the /// destruction of the `Entry` value, see [`into_mut`]. /// /// [`into_mut`]: #method.into_mut diff --git a/src/liballoc/collections/btree/node.rs b/src/liballoc/collections/btree/node.rs index c4f39430533dc..eb0667228d1ff 100644 --- a/src/liballoc/collections/btree/node.rs +++ b/src/liballoc/collections/btree/node.rs @@ -50,11 +50,11 @@ pub const CAPACITY: usize = 2 * B - 1; /// /// We have a separate type for the header and rely on it matching the prefix of `LeafNode`, in /// order to statically allocate a single dummy node to avoid allocations. This struct is -/// `repr(C)` to prevent them from being reordered. `LeafNode` does not just contain a +/// `repr(C)` to prevent them from being reordered. `LeafNode` does not just contain a /// `NodeHeader` because we do not want unnecessary padding between `len` and the keys. -/// Crucially, `NodeHeader` can be safely transmuted to different K and V. (This is exploited +/// Crucially, `NodeHeader` can be safely transmuted to different K and V. (This is exploited /// by `as_header`.) -/// See `into_key_slice` for an explanation of K2. K2 cannot be safely transmuted around +/// See `into_key_slice` for an explanation of K2. K2 cannot be safely transmuted around /// because the size of `NodeHeader` depends on its alignment! #[repr(C)] struct NodeHeader { @@ -1295,7 +1295,7 @@ impl<'a, K, V> Handle, K, V, marker::Internal>, marker:: } } - /// Returns whether it is valid to call `.merge()`, i.e., whether there is enough room in + /// Returns `true` if it is valid to call `.merge()`, i.e., whether there is enough room in /// a node to hold the combination of the nodes to the left and right of this handle along /// with the key/value pair at this handle. pub fn can_merge(&self) -> bool { @@ -1573,7 +1573,7 @@ unsafe fn move_edges( impl Handle, HandleType> { - /// Check whether the underlying node is an `Internal` node or a `Leaf` node. + /// Checks whether the underlying node is an `Internal` node or a `Leaf` node. pub fn force(self) -> ForceResult< Handle, HandleType>, Handle, HandleType> diff --git a/src/liballoc/collections/btree/set.rs b/src/liballoc/collections/btree/set.rs index 78cd21dd4118d..870e3e47692b0 100644 --- a/src/liballoc/collections/btree/set.rs +++ b/src/liballoc/collections/btree/set.rs @@ -556,7 +556,7 @@ impl BTreeSet { Recover::replace(&mut self.map, value) } - /// Removes a value from the set. Returns `true` if the value was + /// Removes a value from the set. Returns whether the value was /// present in the set. /// /// The value may be any borrowed form of the set's value type, @@ -988,7 +988,7 @@ impl<'a, T> DoubleEndedIterator for Range<'a, T> { #[stable(feature = "fused", since = "1.26.0")] impl FusedIterator for Range<'_, T> {} -/// Compare `x` and `y`, but return `short` if x is None and `long` if y is None +/// Compares `x` and `y`, but return `short` if x is None and `long` if y is None fn cmp_opt(x: Option<&T>, y: Option<&T>, short: Ordering, long: Ordering) -> Ordering { match (x, y) { (None, _) => short, diff --git a/src/liballoc/collections/vec_deque.rs b/src/liballoc/collections/vec_deque.rs index 99fa54acb0836..b6fdaa8999212 100644 --- a/src/liballoc/collections/vec_deque.rs +++ b/src/liballoc/collections/vec_deque.rs @@ -124,7 +124,7 @@ impl VecDeque { ptr::write(self.ptr().add(off), value); } - /// Returns `true` if and only if the buffer is at full capacity. + /// Returns `true` if the buffer is at full capacity. #[inline] fn is_full(&self) -> bool { self.cap() - self.len() == 1 @@ -560,7 +560,7 @@ impl VecDeque { /// Does nothing if the capacity is already sufficient. /// /// Note that the allocator may give the collection more space than it - /// requests. Therefore capacity can not be relied upon to be precisely + /// requests. Therefore, capacity can not be relied upon to be precisely /// minimal. Prefer `reserve` if future insertions are expected. /// /// # Errors @@ -924,7 +924,7 @@ impl VecDeque { self.tail == self.head } - /// Create a draining iterator that removes the specified range in the + /// Creates a draining iterator that removes the specified range in the /// `VecDeque` and yields the removed items. /// /// Note 1: The element range is removed even if the iterator is not @@ -932,7 +932,7 @@ impl VecDeque { /// /// Note 2: It is unspecified how many elements are removed from the deque, /// if the `Drain` value is not dropped, but the borrow it holds expires - /// (eg. due to mem::forget). + /// (e.g., due to `mem::forget`). /// /// # Panics /// @@ -1922,7 +1922,7 @@ impl VecDeque { /// /// # Panics /// - /// If `mid` is greater than `len()`. Note that `mid == len()` + /// If `mid` is greater than `len()`. Note that `mid == len()` /// does _not_ panic and is a no-op rotation. /// /// # Complexity @@ -1967,7 +1967,7 @@ impl VecDeque { /// /// # Panics /// - /// If `k` is greater than `len()`. Note that `k == len()` + /// If `k` is greater than `len()`. Note that `k == len()` /// does _not_ panic and is a no-op rotation. /// /// # Complexity diff --git a/src/liballoc/fmt.rs b/src/liballoc/fmt.rs index 9bda7034a621b..d2ba9b001916c 100644 --- a/src/liballoc/fmt.rs +++ b/src/liballoc/fmt.rs @@ -27,7 +27,7 @@ //! will then parse the format string and determine if the list of arguments //! provided is suitable to pass to this format string. //! -//! To convert a single value to a string, use the [`to_string`] method. This +//! To convert a single value to a string, use the [`to_string`] method. This //! will use the [`Display`] formatting trait. //! //! ## Positional parameters @@ -102,7 +102,7 @@ //! When requesting that an argument be formatted with a particular type, you //! are actually requesting that an argument ascribes to a particular trait. //! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as -//! well as [`isize`]). The current mapping of types to traits is: +//! well as [`isize`]). The current mapping of types to traits is: //! //! * *nothing* ⇒ [`Display`] //! * `?` ⇒ [`Debug`] @@ -427,7 +427,7 @@ //! 3. An asterisk `.*`: //! //! `.*` means that this `{...}` is associated with *two* format inputs rather than one: the -//! first input holds the `usize` precision, and the second holds the value to print. Note that +//! first input holds the `usize` precision, and the second holds the value to print. Note that //! in this case, if one uses the format string `{:.*}`, then the `` part refers //! to the *value* to print, and the `precision` must come in the input preceding ``. //! diff --git a/src/liballoc/macros.rs b/src/liballoc/macros.rs index 7ae57a8dc7984..eb3410078513d 100644 --- a/src/liballoc/macros.rs +++ b/src/liballoc/macros.rs @@ -63,18 +63,18 @@ macro_rules! vec { /// Creates a `String` using interpolation of runtime expressions. /// -/// The first argument `format!` receives is a format string. This must be a string -/// literal. The power of the formatting string is in the `{}`s contained. +/// The first argument `format!` receives is a format string. This must be a string +/// literal. The power of the formatting string is in the `{}`s contained. /// /// Additional parameters passed to `format!` replace the `{}`s within the /// formatting string in the order given unless named or positional parameters -/// are used, see [`std::fmt`][fmt] for more information. +/// are used; see [`std::fmt`][fmt] for more information. /// /// A common use for `format!` is concatenation and interpolation of strings. /// The same convention is used with [`print!`] and [`write!`] macros, /// depending on the intended destination of the string. /// -/// To convert a single value to a string, use the [`to_string`] method. This +/// To convert a single value to a string, use the [`to_string`] method. This /// will use the [`Display`] formatting trait. /// /// [fmt]: ../std/fmt/index.html diff --git a/src/liballoc/raw_vec.rs b/src/liballoc/raw_vec.rs index dcecf9bc76d88..fe28fe5095cce 100644 --- a/src/liballoc/raw_vec.rs +++ b/src/liballoc/raw_vec.rs @@ -335,7 +335,7 @@ impl RawVec { /// enough to want to do that it's easiest to just have a dedicated method. Slightly /// more efficient logic can be provided for this than the general case. /// - /// Returns true if the reallocation attempt has succeeded, or false otherwise. + /// Returns `true` if the reallocation attempt has succeeded. /// /// # Panics /// @@ -504,7 +504,7 @@ impl RawVec { /// the requested space. This is not really unsafe, but the unsafe /// code *you* write that relies on the behavior of this function may break. /// - /// Returns true if the reallocation attempt has succeeded, or false otherwise. + /// Returns `true` if the reallocation attempt has succeeded. /// /// # Panics /// diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index d78869270d563..12f75d84211e6 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -512,7 +512,7 @@ impl Rc { this.strong() } - /// Returns true if there are no other `Rc` or [`Weak`][weak] pointers to + /// Returns `true` if there are no other `Rc` or [`Weak`][weak] pointers to /// this inner value. /// /// [weak]: struct.Weak.html @@ -561,7 +561,7 @@ impl Rc { #[inline] #[stable(feature = "ptr_eq", since = "1.17.0")] - /// Returns true if the two `Rc`s point to the same value (not + /// Returns `true` if the two `Rc`s point to the same value (not /// just values that compare as equal). /// /// # Examples @@ -1334,8 +1334,8 @@ impl Weak { }) } - /// Return `None` when the pointer is dangling and there is no allocated `RcBox`, - /// i.e., this `Weak` was created by `Weak::new` + /// Returns `None` when the pointer is dangling and there is no allocated `RcBox` + /// (i.e., when this `Weak` was created by `Weak::new`). #[inline] fn inner(&self) -> Option<&RcBox> { if is_dangling(self.ptr) { @@ -1345,7 +1345,7 @@ impl Weak { } } - /// Returns true if the two `Weak`s point to the same value (not just values + /// Returns `true` if the two `Weak`s point to the same value (not just values /// that compare as equal). /// /// # Notes diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs index 479959deeb1a7..c4f4a80a017df 100644 --- a/src/liballoc/slice.rs +++ b/src/liballoc/slice.rs @@ -205,10 +205,10 @@ impl [T] { /// /// The comparator function must define a total ordering for the elements in the slice. If /// the ordering is not total, the order of the elements is unspecified. An order is a - /// total order if it is (for all a, b and c): + /// total order if it is (for all `a`, `b` and `c`): /// - /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and - /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >. + /// * total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true, and + /// * transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. /// /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`. diff --git a/src/liballoc/string.rs b/src/liballoc/string.rs index 73f67e98f364e..84c35c6f1bd2b 100644 --- a/src/liballoc/string.rs +++ b/src/liballoc/string.rs @@ -963,7 +963,7 @@ impl String { /// Does nothing if the capacity is already sufficient. /// /// Note that the allocator may give the collection more space than it - /// requests. Therefore capacity can not be relied upon to be precisely + /// requests. Therefore, capacity can not be relied upon to be precisely /// minimal. Prefer `reserve` if future insertions are expected. /// /// # Errors @@ -1377,9 +1377,7 @@ impl String { self.vec.len() } - /// Returns `true` if this `String` has a length of zero. - /// - /// Returns `false` otherwise. + /// Returns `true` if this `String` has a length of zero, and `false` otherwise. /// /// # Examples /// diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs index 5bdb3616ed232..b7d7995b540ba 100644 --- a/src/liballoc/sync.rs +++ b/src/liballoc/sync.rs @@ -560,7 +560,7 @@ impl Arc { #[inline] #[stable(feature = "ptr_eq", since = "1.17.0")] - /// Returns true if the two `Arc`s point to the same value (not + /// Returns `true` if the two `Arc`s point to the same value (not /// just values that compare as equal). /// /// # Examples @@ -1191,8 +1191,8 @@ impl Weak { }) } - /// Return `None` when the pointer is dangling and there is no allocated `ArcInner`, - /// i.e., this `Weak` was created by `Weak::new` + /// Returns `None` when the pointer is dangling and there is no allocated `ArcInner`, + /// (i.e., when this `Weak` was created by `Weak::new`). #[inline] fn inner(&self) -> Option<&ArcInner> { if is_dangling(self.ptr) { @@ -1202,7 +1202,7 @@ impl Weak { } } - /// Returns true if the two `Weak`s point to the same value (not just values + /// Returns `true` if the two `Weak`s point to the same value (not just values /// that compare as equal). /// /// # Notes diff --git a/src/liballoc/tests/heap.rs b/src/liballoc/tests/heap.rs index 809d2bc094aee..7bc1aac7c8b59 100644 --- a/src/liballoc/tests/heap.rs +++ b/src/liballoc/tests/heap.rs @@ -2,7 +2,7 @@ use std::alloc::{Global, Alloc, Layout, System}; -/// https://github.com/rust-lang/rust/issues/45955 +/// Issue #45955. #[test] fn alloc_system_overaligned_request() { check_overalign_requests(System) diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs index 57e10498b92db..57723e4d21281 100644 --- a/src/liballoc/vec.rs +++ b/src/liballoc/vec.rs @@ -463,7 +463,7 @@ impl Vec { /// Does nothing if the capacity is already sufficient. /// /// Note that the allocator may give the collection more space than it - /// requests. Therefore capacity can not be relied upon to be precisely + /// requests. Therefore, capacity can not be relied upon to be precisely /// minimal. Prefer `reserve` if future insertions are expected. /// /// # Panics @@ -525,7 +525,7 @@ impl Vec { /// Does nothing if the capacity is already sufficient. /// /// Note that the allocator may give the collection more space than it - /// requests. Therefore capacity can not be relied upon to be precisely + /// requests. Therefore, capacity can not be relied upon to be precisely /// minimal. Prefer `reserve` if future insertions are expected. /// /// # Errors @@ -738,7 +738,7 @@ impl Vec { /// Forces the length of the vector to `new_len`. /// /// This is a low-level operation that maintains none of the normal - /// invariants of the type. Normally changing the length of a vector + /// invariants of the type. Normally changing the length of a vector /// is done using one of the safe operations instead, such as /// [`truncate`], [`resize`], [`extend`], or [`clear`]. /// @@ -2608,7 +2608,7 @@ impl Drain<'_, T> { /// The range from `self.vec.len` to `self.tail_start` contains elements /// that have been moved out. /// Fill that range as much as possible with new elements from the `replace_with` iterator. - /// Return whether we filled the entire range. (`replace_with.next()` didn’t return `None`.) + /// Returns `true` if we filled the entire range. (`replace_with.next()` didn’t return `None`.) unsafe fn fill>(&mut self, replace_with: &mut I) -> bool { let vec = self.vec.as_mut(); let range_start = vec.len; @@ -2628,7 +2628,7 @@ impl Drain<'_, T> { true } - /// Make room for inserting more elements before the tail. + /// Makes room for inserting more elements before the tail. unsafe fn move_tail(&mut self, extra_capacity: usize) { let vec = self.vec.as_mut(); let used_capacity = self.tail_start + self.tail_len; diff --git a/src/libcore/alloc.rs b/src/libcore/alloc.rs index 66a3094d77d01..f49e226a5cb68 100644 --- a/src/libcore/alloc.rs +++ b/src/libcore/alloc.rs @@ -425,7 +425,7 @@ impl fmt::Display for CannotReallocInPlace { /// The `GlobalAlloc` trait is an `unsafe` trait for a number of reasons, and /// implementors must ensure that they adhere to these contracts: /// -/// * It's undefined behavior if global allocators unwind. This restriction may +/// * It's undefined behavior if global allocators unwind. This restriction may /// be lifted in the future, but currently a panic from any of these /// functions may lead to memory unsafety. /// diff --git a/src/libcore/any.rs b/src/libcore/any.rs index 2afd9e0c07237..01ab523a4c3f6 100644 --- a/src/libcore/any.rs +++ b/src/libcore/any.rs @@ -18,7 +18,7 @@ //! //! Consider a situation where we want to log out a value passed to a function. //! We know the value we're working on implements Debug, but we don't know its -//! concrete type. We want to give special treatment to certain types: in this +//! concrete type. We want to give special treatment to certain types: in this //! case printing out the length of String values prior to their value. //! We don't know the concrete type of our value at compile time, so we need to //! use runtime reflection instead. @@ -31,8 +31,8 @@ //! fn log(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::() { //! Some(as_string) => { diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs index d57ca13a334e8..8383d305518ab 100644 --- a/src/libcore/cell.rs +++ b/src/libcore/cell.rs @@ -130,7 +130,7 @@ //! //! This is simply a special - but common - case of the previous: hiding mutability for operations //! that appear to be immutable. The `clone` method is expected to not change the source value, and -//! is declared to take `&self`, not `&mut self`. Therefore any mutation that happens in the +//! is declared to take `&self`, not `&mut self`. Therefore, any mutation that happens in the //! `clone` method must use cell types. For example, `Rc` maintains its reference counts within a //! `Cell`. //! @@ -1133,7 +1133,7 @@ impl<'b, T: ?Sized> Ref<'b, T> { /// The `RefCell` is already immutably borrowed, so this cannot fail. /// /// This is an associated function that needs to be used as - /// `Ref::clone(...)`. A `Clone` implementation or a method would interfere + /// `Ref::clone(...)`. A `Clone` implementation or a method would interfere /// with the widespread use of `r.borrow().clone()` to clone the contents of /// a `RefCell`. #[stable(feature = "cell_extras", since = "1.15.0")] @@ -1145,7 +1145,7 @@ impl<'b, T: ?Sized> Ref<'b, T> { } } - /// Make a new `Ref` for a component of the borrowed data. + /// Makes a new `Ref` for a component of the borrowed data. /// /// The `RefCell` is already immutably borrowed, so this cannot fail. /// @@ -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. @@ -1217,13 +1217,13 @@ impl fmt::Display for Ref<'_, T> { } impl<'b, T: ?Sized> RefMut<'b, T> { - /// Make a new `RefMut` for a component of the borrowed data, e.g., an enum + /// Makes a new `RefMut` for a component of the borrowed data, e.g., an enum /// variant. /// /// The `RefCell` is already mutably borrowed, so this cannot fail. /// /// This is an associated function that needs to be used as - /// `RefMut::map(...)`. A method would interfere with methods of the same + /// `RefMut::map(...)`. A method would interfere with methods of the same /// name on the contents of a `RefCell` used through `Deref`. /// /// # Examples @@ -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 @@ -1416,7 +1416,7 @@ impl fmt::Display for RefMut<'_, T> { /// co-exist with it. A `&mut T` must always be unique. /// /// Note that while mutating or mutably aliasing the contents of an `&UnsafeCell` is -/// okay (provided you enforce the invariants some other way), it is still undefined behavior +/// ok (provided you enforce the invariants some other way), it is still undefined behavior /// to have multiple `&mut UnsafeCell` aliases. /// /// # Examples diff --git a/src/libcore/char/decode.rs b/src/libcore/char/decode.rs index 510c46cdca0ed..133c9169df858 100644 --- a/src/libcore/char/decode.rs +++ b/src/libcore/char/decode.rs @@ -20,7 +20,7 @@ pub struct DecodeUtf16Error { code: u16, } -/// Create an iterator over the UTF-16 encoded code points in `iter`, +/// Creates an iterator over the UTF-16 encoded code points in `iter`, /// returning unpaired surrogates as `Err`s. /// /// # Examples diff --git a/src/libcore/char/methods.rs b/src/libcore/char/methods.rs index fbc9a4a6b8efa..72967b9adf7a0 100644 --- a/src/libcore/char/methods.rs +++ b/src/libcore/char/methods.rs @@ -524,7 +524,7 @@ impl char { } } - /// Returns true if this `char` is an alphabetic code point, and false if not. + /// Returns `true` if this `char` is an alphabetic code point, and false if not. /// /// # Examples /// @@ -548,7 +548,7 @@ impl char { } } - /// Returns true if this `char` satisfies the 'XID_Start' Unicode property, and false + /// Returns `true` if this `char` satisfies the 'XID_Start' Unicode property, and false /// otherwise. /// /// 'XID_Start' is a Unicode Derived Property specified in @@ -562,7 +562,7 @@ impl char { derived_property::XID_Start(self) } - /// Returns true if this `char` satisfies the 'XID_Continue' Unicode property, and false + /// Returns `true` if this `char` satisfies the 'XID_Continue' Unicode property, and false /// otherwise. /// /// 'XID_Continue' is a Unicode Derived Property specified in @@ -576,7 +576,7 @@ impl char { derived_property::XID_Continue(self) } - /// Returns true if this `char` is lowercase, and false otherwise. + /// Returns `true` if this `char` is lowercase. /// /// 'Lowercase' is defined according to the terms of the Unicode Derived Core /// Property `Lowercase`. @@ -604,7 +604,7 @@ impl char { } } - /// Returns true if this `char` is uppercase, and false otherwise. + /// Returns `true` if this `char` is uppercase. /// /// 'Uppercase' is defined according to the terms of the Unicode Derived Core /// Property `Uppercase`. @@ -632,7 +632,7 @@ impl char { } } - /// Returns true if this `char` is whitespace, and false otherwise. + /// Returns `true` if this `char` is whitespace. /// /// 'Whitespace' is defined according to the terms of the Unicode Derived Core /// Property `White_Space`. @@ -659,7 +659,7 @@ impl char { } } - /// Returns true if this `char` is alphanumeric, and false otherwise. + /// Returns `true` if this `char` is alphanumeric. /// /// 'Alphanumeric'-ness is defined in terms of the Unicode General Categories /// 'Nd', 'Nl', 'No' and the Derived Core Property 'Alphabetic'. @@ -684,7 +684,7 @@ impl char { self.is_alphabetic() || self.is_numeric() } - /// Returns true if this `char` is a control code point, and false otherwise. + /// Returns `true` if this `char` is a control code point. /// /// 'Control code point' is defined in terms of the Unicode General /// Category `Cc`. @@ -704,7 +704,7 @@ impl char { general_category::Cc(self) } - /// Returns true if this `char` is an extended grapheme character, and false otherwise. + /// Returns `true` if this `char` is an extended grapheme character. /// /// 'Extended grapheme character' is defined in terms of the Unicode Shaping and Rendering /// Category `Grapheme_Extend`. @@ -713,7 +713,7 @@ impl char { derived_property::Grapheme_Extend(self) } - /// Returns true if this `char` is numeric, and false otherwise. + /// Returns `true` if this `char` is numeric. /// /// 'Numeric'-ness is defined in terms of the Unicode General Categories /// 'Nd', 'Nl', 'No'. diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs index d43a5c1032ce0..81fcdeee12d29 100644 --- a/src/libcore/cmp.rs +++ b/src/libcore/cmp.rs @@ -26,7 +26,7 @@ use self::Ordering::*; /// relations](http://en.wikipedia.org/wiki/Partial_equivalence_relation). /// /// This trait allows for partial equality, for types that do not have a full -/// equivalence relation. For example, in floating point numbers `NaN != NaN`, +/// equivalence relation. For example, in floating point numbers `NaN != NaN`, /// so floating point types implement `PartialEq` but not `Eq`. /// /// Formally, the equality must be (for all `a`, `b` and `c`): diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index d4a1d15e4e7e1..4a7c6e15a4df1 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -220,7 +220,7 @@ pub trait AsMut { /// /// There is one exception to implementing `Into`, and it's kind of esoteric. /// If the destination type is not part of the current crate, and it uses a -/// generic variable, then you can't implement `From` directly. For example, +/// generic variable, then you can't implement `From` directly. For example, /// take this crate: /// /// ```compile_fail diff --git a/src/libcore/default.rs b/src/libcore/default.rs index 0e47c2fd0b5d0..5ad05b3824764 100644 --- a/src/libcore/default.rs +++ b/src/libcore/default.rs @@ -54,7 +54,7 @@ /// /// ## How can I implement `Default`? /// -/// Provide an implementation for the `default()` method that returns the value of +/// Provides an implementation for the `default()` method that returns the value of /// your type that should be the default: /// /// ``` diff --git a/src/libcore/ffi.rs b/src/libcore/ffi.rs index 644380c69f2c7..d88793f2801e7 100644 --- a/src/libcore/ffi.rs +++ b/src/libcore/ffi.rs @@ -184,7 +184,7 @@ impl<'a> VaList<'a> { va_arg(self) } - /// Copy the `va_list` at the current location. + /// Copies the `va_list` at the current location. #[unstable(feature = "c_variadic", reason = "the `c_variadic` feature has not been properly tested on \ all supported platforms", @@ -213,7 +213,7 @@ extern "rust-intrinsic" { /// `va_copy`. fn va_end(ap: &mut VaList); - /// Copy the current location of arglist `src` to the arglist `dst`. + /// Copies the current location of arglist `src` to the arglist `dst`. #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"), not(target_arch = "x86_64")), windows))] diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 530b2f52c0df2..2ce58c803b878 100644 --- a/src/libcore/fmt/mod.rs +++ b/src/libcore/fmt/mod.rs @@ -483,12 +483,12 @@ impl Display for Arguments<'_> { /// implementations, such as [`debug_struct`][debug_struct]. /// /// `Debug` implementations using either `derive` or the debug builder API -/// on [`Formatter`] support pretty printing using the alternate flag: `{:#?}`. +/// on [`Formatter`] support pretty-printing using the alternate flag: `{:#?}`. /// /// [debug_struct]: ../../std/fmt/struct.Formatter.html#method.debug_struct /// [`Formatter`]: ../../std/fmt/struct.Formatter.html /// -/// Pretty printing with `#?`: +/// Pretty-printing with `#?`: /// /// ``` /// #[derive(Debug)] diff --git a/src/libcore/future/future.rs b/src/libcore/future/future.rs index 539b07fc21eea..0f142347a95ba 100644 --- a/src/libcore/future/future.rs +++ b/src/libcore/future/future.rs @@ -60,7 +60,7 @@ pub trait Future { /// progress, meaning that each time the current task is woken up, it should /// actively re-`poll` pending futures that it still has an interest in. /// - /// The `poll` function is not called repeatedly in a tight loop-- instead, + /// The `poll` function is not called repeatedly in a tight loop -- instead, /// it should only be called when the future indicates that it is ready to /// make progress (by calling `wake()`). If you're familiar with the /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index 18f09f4c5dda4..235c79307ab8d 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -10,7 +10,7 @@ use mem; /// An implementation of SipHash 1-3. /// /// This is currently the default hashing function used by standard library -/// (eg. `collections::HashMap` uses it by default). +/// (e.g., `collections::HashMap` uses it by default). /// /// See: #[unstable(feature = "hashmap_internals", issue = "0")] @@ -90,7 +90,7 @@ macro_rules! compress { }); } -/// Load an integer of the desired type from a byte stream, in LE order. Uses +/// Loads an integer of the desired type from a byte stream, in LE order. Uses /// `copy_nonoverlapping` to let the compiler generate the most efficient way /// to load it from a possibly unaligned address. /// @@ -107,7 +107,7 @@ macro_rules! load_int_le { }); } -/// Load an u64 using up to 7 bytes of a byte slice. +/// Loads an u64 using up to 7 bytes of a byte slice. /// /// Unsafe because: unchecked indexing at start..start+len #[inline] diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index ad5a2071a7381..89de5c1bc8af8 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -34,7 +34,7 @@ use intrinsics; /// use std::hint::unreachable_unchecked; /// /// // `b.saturating_add(1)` is always positive (not zero), -/// // hence `checked_div` will never return None. +/// // hence `checked_div` will never return `None`. /// // Therefore, the else branch is unreachable. /// a.checked_div(b.saturating_add(1)) /// .unwrap_or_else(|| unsafe { unreachable_unchecked() }) diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs index e927ed40d7fb7..f6de7566be914 100644 --- a/src/libcore/intrinsics.rs +++ b/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 //! @@ -315,35 +315,35 @@ extern "rust-intrinsic" { /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap). pub fn atomic_xchg_relaxed(dst: *mut T, src: T) -> T; - /// Add to the current value, returning the previous value. + /// Adds to the current value, returning the previous value. /// The stabilized version of this intrinsic is available on the /// `std::sync::atomic` types via the `fetch_add` method by passing /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html) /// as the `order`. For example, /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add). pub fn atomic_xadd(dst: *mut T, src: T) -> T; - /// Add to the current value, returning the previous value. + /// Adds to the current value, returning the previous value. /// The stabilized version of this intrinsic is available on the /// `std::sync::atomic` types via the `fetch_add` method by passing /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html) /// as the `order`. For example, /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add). pub fn atomic_xadd_acq(dst: *mut T, src: T) -> T; - /// Add to the current value, returning the previous value. + /// Adds to the current value, returning the previous value. /// The stabilized version of this intrinsic is available on the /// `std::sync::atomic` types via the `fetch_add` method by passing /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html) /// as the `order`. For example, /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add). pub fn atomic_xadd_rel(dst: *mut T, src: T) -> T; - /// Add to the current value, returning the previous value. + /// Adds to the current value, returning the previous value. /// The stabilized version of this intrinsic is available on the /// `std::sync::atomic` types via the `fetch_add` method by passing /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html) /// as the `order`. For example, /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add). pub fn atomic_xadd_acqrel(dst: *mut T, src: T) -> T; - /// Add to the current value, returning the previous value. + /// Adds to the current value, returning the previous value. /// The stabilized version of this intrinsic is available on the /// `std::sync::atomic` types via the `fetch_add` method by passing /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html) @@ -556,7 +556,7 @@ extern "rust-intrinsic" { pub fn atomic_umax_relaxed(dst: *mut T, src: T) -> T; /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a noop. + /// if supported; otherwise, it is a no-op. /// Prefetches have no effect on the behavior of the program but can change its performance /// characteristics. /// @@ -564,7 +564,7 @@ extern "rust-intrinsic" { /// ranging from (0) - no locality, to (3) - extremely local keep in cache pub fn prefetch_read_data(data: *const T, locality: i32); /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a noop. + /// if supported; otherwise, it is a no-op. /// Prefetches have no effect on the behavior of the program but can change its performance /// characteristics. /// @@ -572,7 +572,7 @@ extern "rust-intrinsic" { /// ranging from (0) - no locality, to (3) - extremely local keep in cache pub fn prefetch_write_data(data: *const T, locality: i32); /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a noop. + /// if supported; otherwise, it is a no-op. /// Prefetches have no effect on the behavior of the program but can change its performance /// characteristics. /// @@ -580,7 +580,7 @@ extern "rust-intrinsic" { /// ranging from (0) - no locality, to (3) - extremely local keep in cache pub fn prefetch_read_instruction(data: *const T, locality: i32); /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a noop. + /// if supported; otherwise, it is a no-op. /// Prefetches have no effect on the behavior of the program but can change its performance /// characteristics. /// @@ -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; @@ -857,7 +857,7 @@ extern "rust-intrinsic" { /// /// // The no-copy, unsafe way, still using transmute, but not UB. /// // This is equivalent to the original, but safer, and reuses the - /// // same Vec internals. Therefore the new inner type must have the + /// // same `Vec` internals. Therefore, the new inner type must have the /// // exact same size, and the same alignment, as the old type. /// // The same caveats exist for this method as transmute, for /// // the original inner type (`&i32`) to the converted inner type @@ -875,8 +875,8 @@ extern "rust-intrinsic" { /// ``` /// use std::{slice, mem}; /// - /// // There are multiple ways to do this; and there are multiple problems - /// // with the following, transmute, way. + /// // There are multiple ways to do this, and there are multiple problems + /// // with the following (transmute) way. /// fn split_at_mut_transmute(slice: &mut [T], mid: usize) /// -> (&mut [T], &mut [T]) { /// let len = slice.len(); @@ -988,7 +988,7 @@ extern "rust-intrinsic" { /// beginning at `dst` with the same size. /// /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of - /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values + /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values /// in the region beginning at `*src` and the region beginning at `*dst` can /// [violate memory safety][read-ownership]. /// @@ -1055,7 +1055,7 @@ extern "rust-intrinsic" { /// [`copy_nonoverlapping`] can be used instead. /// /// `copy` is semantically equivalent to C's [`memmove`], but with the argument - /// order swapped. Copying takes place as if the bytes were copied from `src` + /// order swapped. Copying takes place as if the bytes were copied from `src` /// to a temporary array and then copied from the array to `dst`. /// /// [`copy_nonoverlapping`]: ./fn.copy_nonoverlapping.html @@ -1072,7 +1072,7 @@ extern "rust-intrinsic" { /// * Both `src` and `dst` must be properly aligned. /// /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of - /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values + /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values /// in the region beginning at `*src` and the region beginning at `*dst` can /// [violate memory safety][read-ownership]. /// @@ -1200,19 +1200,19 @@ extern "rust-intrinsic" { /// unless size is equal to zero. pub fn volatile_set_memory(dst: *mut T, val: u8, count: usize); - /// Perform a volatile load from the `src` pointer. + /// Performs a volatile load from the `src` pointer. /// The stabilized version of this intrinsic is /// [`std::ptr::read_volatile`](../../std/ptr/fn.read_volatile.html). pub fn volatile_load(src: *const T) -> T; - /// Perform a volatile store to the `dst` pointer. + /// Performs a volatile store to the `dst` pointer. /// The stabilized version of this intrinsic is /// [`std::ptr::write_volatile`](../../std/ptr/fn.write_volatile.html). pub fn volatile_store(dst: *mut T, val: T); - /// Perform a volatile load from the `src` pointer + /// Performs a volatile load from the `src` pointer /// The pointer is not required to be aligned. pub fn unaligned_volatile_load(src: *const T) -> T; - /// Perform a volatile store to the `dst` pointer. + /// Performs a volatile store to the `dst` pointer. /// The pointer is not required to be aligned. pub fn unaligned_volatile_store(dst: *mut T, val: T); diff --git a/src/libcore/iter/range.rs b/src/libcore/iter/range.rs index 66c09a0ddd0fb..a3e9cfa949312 100644 --- a/src/libcore/iter/range.rs +++ b/src/libcore/iter/range.rs @@ -20,19 +20,19 @@ pub trait Step: Clone + PartialOrd + Sized { /// without overflow. fn steps_between(start: &Self, end: &Self) -> Option; - /// Replaces this step with `1`, returning itself + /// Replaces this step with `1`, returning itself. fn replace_one(&mut self) -> Self; - /// Replaces this step with `0`, returning itself + /// Replaces this step with `0`, returning itself. fn replace_zero(&mut self) -> Self; - /// Adds one to this step, returning the result + /// Adds one to this step, returning the result. fn add_one(&self) -> Self; - /// Subtracts one to this step, returning the result + /// Subtracts one to this step, returning the result. fn sub_one(&self) -> Self; - /// Add an usize, returning None on overflow + /// Adds a `usize`, returning `None` on overflow. fn add_usize(&self, n: usize) -> Option; } diff --git a/src/libcore/iter/traits/exact_size.rs b/src/libcore/iter/traits/exact_size.rs index 3bfba29e21960..d6eab40213edb 100644 --- a/src/libcore/iter/traits/exact_size.rs +++ b/src/libcore/iter/traits/exact_size.rs @@ -104,7 +104,7 @@ pub trait ExactSizeIterator: Iterator { lower } - /// Returns whether the iterator is empty. + /// Returns `true` if the iterator is empty. /// /// This method has a default implementation using `self.len()`, so you /// don't need to implement it yourself. diff --git a/src/libcore/iter/traits/iterator.rs b/src/libcore/iter/traits/iterator.rs index 218c7199f35a6..861e9c3157a79 100644 --- a/src/libcore/iter/traits/iterator.rs +++ b/src/libcore/iter/traits/iterator.rs @@ -120,7 +120,7 @@ pub trait Iterator { /// // ... and then None once it's over. /// assert_eq!(None, iter.next()); /// - /// // More calls may or may not return None. Here, they always will. + /// // More calls may or may not return `None`. Here, they always will. /// assert_eq!(None, iter.next()); /// assert_eq!(None, iter.next()); /// ``` @@ -564,9 +564,9 @@ pub trait Iterator { /// Calls a closure on each element of an iterator. /// /// This is equivalent to using a [`for`] loop on the iterator, although - /// `break` and `continue` are not possible from a closure. It's generally + /// `break` and `continue` are not possible from a closure. It's generally /// more idiomatic to use a `for` loop, but `for_each` may be more legible - /// when processing items at the end of longer iterator chains. In some + /// when processing items at the end of longer iterator chains. In some /// cases `for_each` may also be faster than a loop, because it will use /// internal iteration on adaptors like `Chain`. /// @@ -1215,7 +1215,7 @@ pub trait Iterator { /// assert_eq!(iter.next(), Some(4)); /// assert_eq!(iter.next(), None); /// - /// // it will always return None after the first time. + /// // it will always return `None` after the first time. /// assert_eq!(iter.next(), None); /// assert_eq!(iter.next(), None); /// assert_eq!(iter.next(), None); @@ -1515,7 +1515,7 @@ pub trait Iterator { /// is propagated back to the caller immediately (short-circuiting). /// /// The initial value is the value the accumulator will have on the first - /// call. If applying the closure succeeded against every element of the + /// call. If applying the closure succeeded against every element of the /// iterator, `try_fold()` returns the final accumulator as success. /// /// Folding is useful whenever you have a collection of something, and want @@ -1528,10 +1528,10 @@ pub trait Iterator { /// do something better than the default `for` loop implementation. /// /// In particular, try to have this call `try_fold()` on the internal parts - /// from which this iterator is composed. If multiple calls are needed, + /// from which this iterator is composed. If multiple calls are needed, /// the `?` operator may be convenient for chaining the accumulator value /// along, but beware any invariants that need to be upheld before those - /// early returns. This is a `&mut self` method, so iteration needs to be + /// early returns. This is a `&mut self` method, so iteration needs to be /// resumable after hitting an error here. /// /// # Examples diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 6b5fe84ff61df..2eb506cedd4f8 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -1,4 +1,4 @@ -/// Entry point of thread panic, for details, see std::macros +/// Entry point of thread panic. For details, see `std::macros`. #[macro_export] #[cfg_attr(not(stage0), allow_internal_unstable(core_panic, __rust_unstable_column))] #[cfg_attr(stage0, allow_internal_unstable)] @@ -434,7 +434,7 @@ macro_rules! writeln { /// * Iterators that dynamically terminate. /// /// If the determination that the code is unreachable proves incorrect, the -/// program immediately terminates with a [`panic!`]. The function [`unreachable_unchecked`], +/// program immediately terminates with a [`panic!`]. The function [`unreachable_unchecked`], /// which belongs to the [`std::hint`] module, informs the compiler to /// optimize the code out of the release version entirely. /// @@ -495,7 +495,7 @@ macro_rules! unreachable { /// A standardized placeholder for marking unfinished code. /// /// This can be useful if you are prototyping and are just looking to have your -/// code typecheck, or if you're implementing a trait that requires multiple +/// code type-check, or if you're implementing a trait that requires multiple /// methods, and you're only planning on using one of them. /// /// # Panics diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs index 2f86e13b93816..2a493e88fe896 100644 --- a/src/libcore/mem.rs +++ b/src/libcore/mem.rs @@ -295,7 +295,7 @@ pub const fn size_of() -> usize { /// Returns the size of the pointed-to value in bytes. /// /// This is usually the same as `size_of::()`. However, when `T` *has* no -/// statically known size, e.g., a slice [`[T]`][slice] or a [trait object], +/// statically-known size, e.g., a slice [`[T]`][slice] or a [trait object], /// then `size_of_val` can be used to get the dynamically-known size. /// /// [slice]: ../../std/primitive.slice.html @@ -403,7 +403,7 @@ pub fn align_of_val(val: &T) -> usize { unsafe { intrinsics::min_align_of_val(val) } } -/// Returns whether dropping values of type `T` matters. +/// Returns `true` if dropping values of type `T` matters. /// /// This is purely an optimization hint, and may be implemented conservatively: /// it may return `true` for types that don't actually need to be dropped. @@ -958,7 +958,7 @@ impl ManuallyDrop { ManuallyDrop { value } } - /// Extract the value from the `ManuallyDrop` container. + /// Extracts the value from the `ManuallyDrop` container. /// /// This allows the value to be dropped again. /// @@ -1038,26 +1038,29 @@ impl DerefMut for ManuallyDrop { /// A newtype to construct uninitialized instances of `T`. /// /// The compiler, in general, assumes that variables are properly initialized -/// at their respective type. For example, a variable of reference type must -/// be aligned and non-NULL. This is an invariant that must *always* be upheld, -/// even in unsafe code. As a consequence, 0-initializing a variable of reference +/// at their respective type. For example, a variable of reference type must +/// be aligned and non-NULL. This is an invariant that must *always* be upheld, +/// even in unsafe code. As a consequence, zero-initializing a variable of reference /// type causes instantaneous undefined behavior, no matter whether that reference /// ever gets used to access memory: +/// /// ```rust,no_run /// use std::mem; /// /// let x: &i32 = unsafe { mem::zeroed() }; // undefined behavior! /// ``` +/// /// This is exploited by the compiler for various optimizations, such as eliding /// run-time checks and optimizing `enum` layout. /// -/// Not initializing memory at all (instead of 0-initializing it) causes the same +/// Not initializing memory at all (instead of zero--initializing it) causes the same /// issue: after all, the initial value of the variable might just happen to be /// one that violates the invariant. /// /// `MaybeUninit` serves to enable unsafe code to deal with uninitialized data: /// it is a signal to the compiler indicating that the data here might *not* /// be initialized: +/// /// ```rust /// #![feature(maybe_uninit)] /// use std::mem::MaybeUninit; @@ -1070,6 +1073,7 @@ impl DerefMut for ManuallyDrop { /// // initializing `x`! /// let x = unsafe { x.into_initialized() }; /// ``` +/// /// The compiler then knows to not optimize this code. #[allow(missing_debug_implementations)] #[unstable(feature = "maybe_uninit", issue = "53491")] @@ -1090,7 +1094,7 @@ impl MaybeUninit { MaybeUninit { value: ManuallyDrop::new(val) } } - /// Create a new `MaybeUninit` in an uninitialized state. + /// Creates a new `MaybeUninit` in an uninitialized state. /// /// Note that dropping a `MaybeUninit` will never call `T`'s drop code. /// It is your responsibility to make sure `T` gets dropped if it got initialized. @@ -1100,8 +1104,8 @@ impl MaybeUninit { MaybeUninit { uninit: () } } - /// Create a new `MaybeUninit` in an uninitialized state, with the memory being - /// filled with `0` bytes. It depends on `T` whether that already makes for + /// Creates a new `MaybeUninit` in an uninitialized state, with the memory being + /// filled with `0` bytes. It depends on `T` whether that already makes for /// proper initialization. For example, `MaybeUninit::zeroed()` is initialized, /// but `MaybeUninit<&'static i32>::zeroed()` is not because references must not /// be null. @@ -1118,9 +1122,9 @@ impl MaybeUninit { u } - /// Set the value of the `MaybeUninit`. This overwrites any previous value without dropping it. - /// For your convenience, this also returns a mutable reference to the (now - /// safely initialized) content of `self`. + /// Sets the value of the `MaybeUninit`. This overwrites any previous value without dropping it. + /// For your convenience, this also returns a mutable reference to the (now safely initialized) + /// contents of `self`. #[unstable(feature = "maybe_uninit", issue = "53491")] #[inline(always)] pub fn set(&mut self, val: T) -> &mut T { @@ -1130,7 +1134,7 @@ impl MaybeUninit { } } - /// Extract the value from the `MaybeUninit` container. This is a great way + /// Extracts the value from the `MaybeUninit` container. This is a great way /// to ensure that the data will get dropped, because the resulting `T` is /// subject to the usual drop handling. /// @@ -1145,7 +1149,7 @@ impl MaybeUninit { ManuallyDrop::into_inner(self.value) } - /// Deprecated alternative to `into_initialized`. Will never get stabilized. + /// Deprecated alternative to `into_initialized`. Will never get stabilized. /// Exists only to transition stdsimd to `into_initialized`. #[inline(always)] #[allow(unused)] @@ -1153,7 +1157,7 @@ impl MaybeUninit { self.into_initialized() } - /// Get a reference to the contained value. + /// Gets a reference to the contained value. /// /// # Unsafety /// @@ -1165,7 +1169,7 @@ impl MaybeUninit { &*self.value } - /// Get a mutable reference to the contained value. + /// Gets a mutable reference to the contained value. /// /// # Unsafety /// @@ -1180,7 +1184,7 @@ impl MaybeUninit { &mut *self.value } - /// Get a pointer to the contained value. Reading from this pointer or turning it + /// Gets a pointer to the contained value. Reading from this pointer or turning it /// into a reference will be undefined behavior unless the `MaybeUninit` is initialized. #[unstable(feature = "maybe_uninit", issue = "53491")] #[inline(always)] @@ -1188,7 +1192,7 @@ impl MaybeUninit { unsafe { &*self.value as *const T } } - /// Get a mutable pointer to the contained value. Reading from this pointer or turning it + /// Get sa mutable pointer to the contained value. Reading from this pointer or turning it /// into a reference will be undefined behavior unless the `MaybeUninit` is initialized. #[unstable(feature = "maybe_uninit", issue = "53491")] #[inline(always)] @@ -1196,14 +1200,14 @@ impl MaybeUninit { unsafe { &mut *self.value as *mut T } } - /// Get a pointer to the first element of the array. + /// Gets a pointer to the first element of the array. #[unstable(feature = "maybe_uninit", issue = "53491")] #[inline(always)] pub fn first_ptr(this: &[MaybeUninit]) -> *const T { this as *const [MaybeUninit] as *const T } - /// Get a mutable pointer to the first element of the array. + /// Gets a mutable pointer to the first element of the array. #[unstable(feature = "maybe_uninit", issue = "53491")] #[inline(always)] pub fn first_ptr_mut(this: &mut [MaybeUninit]) -> *mut T { diff --git a/src/libcore/num/dec2flt/algorithm.rs b/src/libcore/num/dec2flt/algorithm.rs index d56fa9662a994..3b57bb7544b35 100644 --- a/src/libcore/num/dec2flt/algorithm.rs +++ b/src/libcore/num/dec2flt/algorithm.rs @@ -61,7 +61,7 @@ mod fpu_precision { unsafe { asm!("fldcw $0" :: "m" (cw) :: "volatile") } } - /// Set the precision field of the FPU to `T` and return a `FPUControlWord` + /// Sets the precision field of the FPU to `T` and returns a `FPUControlWord`. pub fn set_precision() -> FPUControlWord { let cw = 0u16; diff --git a/src/libcore/num/dec2flt/mod.rs b/src/libcore/num/dec2flt/mod.rs index 14a912872be35..47ea5aa5ff000 100644 --- a/src/libcore/num/dec2flt/mod.rs +++ b/src/libcore/num/dec2flt/mod.rs @@ -37,7 +37,7 @@ //! //! In addition, there are numerous helper functions that are used in the paper but not available //! in Rust (or at least in core). Our version is additionally complicated by the need to handle -//! overflow and underflow and the desire to handle subnormal numbers. Bellerophon and +//! overflow and underflow and the desire to handle subnormal numbers. Bellerophon and //! Algorithm R have trouble with overflow, subnormals, and underflow. We conservatively switch to //! Algorithm M (with the modifications described in section 8 of the paper) well before the //! inputs get into the critical region. @@ -54,7 +54,7 @@ //! operations as well, if you want 0.5 ULP accuracy you need to do *everything* in full precision //! and round *exactly once, at the end*, by considering all truncated bits at once. //! -//! FIXME Although some code duplication is necessary, perhaps parts of the code could be shuffled +//! FIXME: Although some code duplication is necessary, perhaps parts of the code could be shuffled //! around such that less code is duplicated. Large parts of the algorithms are independent of the //! float type to output, or only needs access to a few constants, which could be passed in as //! parameters. @@ -148,7 +148,7 @@ macro_rules! from_str_float_impl { /// # Return value /// /// `Err(ParseFloatError)` if the string did not represent a valid - /// number. Otherwise, `Ok(n)` where `n` is the floating-point + /// number. Otherwise, `Ok(n)` where `n` is the floating-point /// number represented by `src`. #[inline] fn from_str(src: &str) -> Result { @@ -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..]), @@ -219,7 +219,7 @@ fn extract_sign(s: &str) -> (Sign, &str) { } } -/// Convert a decimal string into a floating point number. +/// Converts a decimal string into a floating point number. fn dec2flt(s: &str) -> Result { if s.is_empty() { return Err(pfe_empty()) diff --git a/src/libcore/num/dec2flt/num.rs b/src/libcore/num/dec2flt/num.rs index b76c58cc66e6b..126713185711b 100644 --- a/src/libcore/num/dec2flt/num.rs +++ b/src/libcore/num/dec2flt/num.rs @@ -27,7 +27,7 @@ pub fn compare_with_half_ulp(f: &Big, ones_place: usize) -> Ordering { Equal } -/// Convert an ASCII string containing only decimal digits to a `u64`. +/// Converts an ASCII string containing only decimal digits to a `u64`. /// /// Does not perform checks for overflow or invalid characters, so if the caller is not careful, /// the result is bogus and can panic (though it won't be `unsafe`). Additionally, empty strings @@ -44,7 +44,7 @@ pub fn from_str_unchecked<'a, T>(bytes: T) -> u64 where T : IntoIterator Big { @@ -69,7 +69,7 @@ pub fn to_u64(x: &Big) -> u64 { } -/// Extract a range of bits. +/// Extracts a range of bits. /// Index 0 is the least significant bit and the range is half-open as usual. /// Panics if asked to extract more bits than fit into the return type. diff --git a/src/libcore/num/dec2flt/parse.rs b/src/libcore/num/dec2flt/parse.rs index 9e075e43303b6..933f8c1d3f781 100644 --- a/src/libcore/num/dec2flt/parse.rs +++ b/src/libcore/num/dec2flt/parse.rs @@ -42,7 +42,7 @@ pub enum ParseResult<'a> { Invalid, } -/// Check if the input string is a valid floating point number and if so, locate the integral +/// Checks if the input string is a valid floating point number and if so, locate the integral /// part, the fractional part, and the exponent in it. Does not handle signs. pub fn parse_decimal(s: &str) -> ParseResult { if s.is_empty() { diff --git a/src/libcore/num/dec2flt/rawfp.rs b/src/libcore/num/dec2flt/rawfp.rs index 6976bd1a0eefd..b65f539b29c97 100644 --- a/src/libcore/num/dec2flt/rawfp.rs +++ b/src/libcore/num/dec2flt/rawfp.rs @@ -59,10 +59,10 @@ pub trait RawFloat /// Type used by `to_bits` and `from_bits`. type Bits: Add + From + TryFrom; - /// 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 10e from a pre-computed table. + /// Gets the value 10e from a pre-computed table. /// Panics for `e >= CEIL_LOG5_OF_MAX_SIG`. fn short_fast_pow10(e: usize) -> Self; @@ -240,7 +240,7 @@ impl RawFloat for f64 { fn from_bits(v: Self::Bits) -> Self { Self::from_bits(v) } } -/// Convert an Fp to the closest machine float type. +/// Converts an `Fp` to the closest machine float type. /// Does not handle subnormal results. pub fn fp_to_float(x: Fp) -> T { let x = x.normalize(); @@ -319,7 +319,7 @@ pub fn big_to_fp(f: &Big) -> Fp { } } -/// Find the largest floating point number strictly smaller than the argument. +/// Finds the largest floating point number strictly smaller than the argument. /// Does not handle subnormals, zero, or exponent underflow. pub fn prev_float(x: T) -> T { match x.classify() { diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index 68da79135d3a3..dc0580764acb7 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -144,7 +144,7 @@ pub mod consts { #[lang = "f32"] #[cfg(not(test))] impl f32 { - /// Returns `true` if this value is `NaN` and false otherwise. + /// Returns `true` if this value is `NaN`. /// /// ``` /// use std::f32; @@ -169,8 +169,8 @@ impl f32 { f32::from_bits(self.to_bits() & 0x7fff_ffff) } - /// Returns `true` if this value is positive infinity or negative infinity and - /// false otherwise. + /// Returns `true` if this value is positive infinity or negative infinity, and + /// `false` otherwise. /// /// ``` /// use std::f32; @@ -272,7 +272,7 @@ impl f32 { } } - /// Returns `true` if and only if `self` has a positive sign, including `+0.0`, `NaN`s with + /// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with /// positive sign bit and positive infinity. /// /// ``` @@ -288,7 +288,7 @@ impl f32 { !self.is_sign_negative() } - /// Returns `true` if and only if `self` has a negative sign, including `-0.0`, `NaN`s with + /// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with /// negative sign bit and negative infinity. /// /// ``` diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs index b677391548146..c3677f8c8faea 100644 --- a/src/libcore/num/f64.rs +++ b/src/libcore/num/f64.rs @@ -144,7 +144,7 @@ pub mod consts { #[lang = "f64"] #[cfg(not(test))] impl f64 { - /// Returns `true` if this value is `NaN` and false otherwise. + /// Returns `true` if this value is `NaN`. /// /// ``` /// use std::f64; @@ -169,8 +169,8 @@ impl f64 { f64::from_bits(self.to_bits() & 0x7fff_ffff_ffff_ffff) } - /// Returns `true` if this value is positive infinity or negative infinity and - /// false otherwise. + /// Returns `true` if this value is positive infinity or negative infinity, and + /// `false` otherwise. /// /// ``` /// use std::f64; @@ -272,7 +272,7 @@ impl f64 { } } - /// Returns `true` if and only if `self` has a positive sign, including `+0.0`, `NaN`s with + /// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with /// positive sign bit and positive infinity. /// /// ``` @@ -296,7 +296,7 @@ impl f64 { self.is_sign_positive() } - /// Returns `true` if and only if `self` has a negative sign, including `-0.0`, `NaN`s with + /// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with /// negative sign bit and negative infinity. /// /// ``` diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index d34173dafb351..6fb67ea9c9acb 100644 --- a/src/libcore/num/mod.rs +++ b/src/libcore/num/mod.rs @@ -52,7 +52,7 @@ assert_eq!(size_of::>(), size_of::<", s } impl $Ty { - /// Create a non-zero without checking the value. + /// Creates a non-zero without checking the value. /// /// # Safety /// @@ -63,7 +63,7 @@ assert_eq!(size_of::>(), size_of::<", s $Ty(n) } - /// Create a non-zero if the given value is not zero. + /// Creates a non-zero if the given value is not zero. #[$stability] #[inline] pub fn new(n: $Int) -> Option { diff --git a/src/libcore/ops/arith.rs b/src/libcore/ops/arith.rs index 7d8bf18d33a01..0252edee23125 100644 --- a/src/libcore/ops/arith.rs +++ b/src/libcore/ops/arith.rs @@ -49,7 +49,7 @@ /// } /// /// // Notice that the implementation uses the associated type `Output`. -/// impl> Add for Point { +/// impl> Add for Point { /// type Output = Point; /// /// fn add(self, other: Point) -> Point { @@ -157,7 +157,7 @@ add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 } /// } /// /// // Notice that the implementation uses the associated type `Output`. -/// impl> Sub for Point { +/// impl> Sub for Point { /// type Output = Point; /// /// fn sub(self, other: Point) -> Point { @@ -518,7 +518,7 @@ pub trait Rem { macro_rules! rem_impl_integer { ($($t:ty)*) => ($( - /// This operation satisfies `n % d == n - (n / d) * d`. The + /// This operation satisfies `n % d == n - (n / d) * d`. The /// result has the same sign as the left operand. #[stable(feature = "rust1", since = "1.0.0")] impl Rem for $t { diff --git a/src/libcore/ops/range.rs b/src/libcore/ops/range.rs index 815a4cfeed88e..b3dd5d20299c1 100644 --- a/src/libcore/ops/range.rs +++ b/src/libcore/ops/range.rs @@ -52,7 +52,7 @@ impl fmt::Debug for RangeFull { /// (`start..end`). /// /// The `Range` `start..end` contains all values with `x >= start` and -/// `x < end`. It is empty unless `start < end`. +/// `x < end`. It is empty unless `start < end`. /// /// # Examples /// @@ -297,7 +297,7 @@ impl> RangeTo { /// A range bounded inclusively below and above (`start..=end`). /// /// The `RangeInclusive` `start..=end` contains all values with `x >= start` -/// and `x <= end`. It is empty unless `start <= end`. +/// and `x <= end`. It is empty unless `start <= end`. /// /// This iterator is [fused], but the specific values of `start` and `end` after /// iteration has finished are **unspecified** other than that [`.is_empty()`] diff --git a/src/libcore/ops/try.rs b/src/libcore/ops/try.rs index 380bd12131cf6..9fa2c81954ee1 100644 --- a/src/libcore/ops/try.rs +++ b/src/libcore/ops/try.rs @@ -1,7 +1,7 @@ /// A trait for customizing the behavior of the `?` operator. /// /// A type implementing `Try` is one that has a canonical way to view it -/// in terms of a success/failure dichotomy. This trait allows both +/// in terms of a success/failure dichotomy. This trait allows both /// extracting those success or failure values from an existing instance and /// creating a new instance from a success or failure value. #[unstable(feature = "try_trait", issue = "42327")] diff --git a/src/libcore/option.rs b/src/libcore/option.rs index 0e54397db0247..76ef36ac30962 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -214,7 +214,7 @@ impl Option { /// /// # Examples /// - /// Convert an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, preserving the original. + /// Converts an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, preserving the original. /// The [`map`] method takes the `self` argument by value, consuming the original, /// so this technique uses `as_ref` to first take an `Option` to a reference /// to the value inside the original. @@ -395,7 +395,7 @@ impl Option { /// /// # Examples /// - /// Convert an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, consuming the original: + /// Converts an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, consuming the original: /// /// [`String`]: ../../std/string/struct.String.html /// [`usize`]: ../../std/primitive.usize.html @@ -963,7 +963,7 @@ impl Option { /// /// # Examples /// - /// Convert a string to an integer, turning poorly-formed strings + /// Converts a string to an integer, turning poorly-formed strings /// into 0 (the default value for integers). [`parse`] converts /// a string to any other type that implements [`FromStr`], returning /// [`None`] on error. diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs index 56a32c928fb3d..ee9098d73ee92 100644 --- a/src/libcore/pin.rs +++ b/src/libcore/pin.rs @@ -199,7 +199,7 @@ impl Pin

{ Pin { pointer } } - /// Get a pinned shared reference from this pinned pointer. + /// Gets a pinned shared reference from this pinned pointer. #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] pub fn as_ref(self: &Pin

) -> Pin<&P::Target> { @@ -208,7 +208,7 @@ impl Pin

{ } impl Pin

{ - /// Get a pinned mutable reference from this pinned pointer. + /// Gets a pinned mutable reference from this pinned pointer. #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] pub fn as_mut(self: &mut Pin

) -> Pin<&mut P::Target> { @@ -247,7 +247,7 @@ impl<'a, T: ?Sized> Pin<&'a T> { Pin::new_unchecked(new_pointer) } - /// Get a shared reference out of a pin. + /// Gets a shared reference out of a pin. /// /// Note: `Pin` also implements `Deref` to the target, which can be used /// to access the inner value. However, `Deref` only provides a reference @@ -262,14 +262,14 @@ impl<'a, T: ?Sized> Pin<&'a T> { } impl<'a, T: ?Sized> Pin<&'a mut T> { - /// Convert this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime. + /// Converts this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime. #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] pub fn into_ref(self: Pin<&'a mut T>) -> Pin<&'a T> { Pin { pointer: self.pointer } } - /// Get a mutable reference to the data inside of this `Pin`. + /// Gets a mutable reference to the data inside of this `Pin`. /// /// This requires that the data inside this `Pin` is `Unpin`. /// @@ -286,7 +286,7 @@ impl<'a, T: ?Sized> Pin<&'a mut T> { self.pointer } - /// Get a mutable reference to the data inside of this `Pin`. + /// Gets a mutable reference to the data inside of this `Pin`. /// /// # Safety /// diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs index 537aa92c2cf4e..866c8d0896b3c 100644 --- a/src/libcore/ptr.rs +++ b/src/libcore/ptr.rs @@ -12,7 +12,7 @@ //! to access only a single value, in which case the documentation omits the size //! and implicitly assumes it to be `size_of::()` bytes. //! -//! The precise rules for validity are not determined yet. The guarantees that are +//! The precise rules for validity are not determined yet. The guarantees that are //! provided at this point are very minimal: //! //! * A [null] pointer is *never* valid, not even for accesses of [size zero][zst]. @@ -104,7 +104,7 @@ pub use intrinsics::write_bytes; /// /// * `to_drop` must be [valid] for reads. /// -/// * `to_drop` must be properly aligned. See the example below for how to drop +/// * `to_drop` must be properly aligned. See the example below for how to drop /// an unaligned pointer. /// /// Additionally, if `T` is not [`Copy`], using the pointed-to value after @@ -135,7 +135,7 @@ pub use intrinsics::write_bytes; /// unsafe { /// // Get a raw pointer to the last element in `v`. /// let ptr = &mut v[1] as *mut _; -/// // Shorten `v` to prevent the last item from being dropped. We do that first, +/// // Shorten `v` to prevent the last item from being dropped. We do that first, /// // to prevent issues if the `drop_in_place` below panics. /// v.set_len(1); /// // Without a call `drop_in_place`, the last item would never be dropped, @@ -531,7 +531,7 @@ pub unsafe fn replace(dst: *mut T, mut src: T) -> T { /// /// `read` creates a bitwise copy of `T`, regardless of whether `T` is [`Copy`]. /// If `T` is not [`Copy`], using both the returned value and the value at -/// `*src` can violate memory safety. Note that assigning to `*src` counts as a +/// `*src` can violate memory safety. Note that assigning to `*src` counts as a /// use because it will attempt to drop the value at `*src`. /// /// [`write`] can be used to overwrite data without causing it to be dropped. @@ -588,7 +588,7 @@ pub unsafe fn read(src: *const T) -> T { /// * `src` must be [valid] for reads. /// /// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of -/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned +/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned /// value and the value at `*src` can [violate memory safety][read-ownership]. /// /// Note that even if `T` has size `0`, the pointer must be non-NULL. @@ -825,7 +825,7 @@ pub unsafe fn write_unaligned(dst: *mut T, src: T) { /// /// The compiler shouldn't change the relative order or number of volatile /// memory operations. However, volatile memory operations on zero-sized types -/// (e.g., if a zero-sized type is passed to `read_volatile`) are no-ops +/// (e.g., if a zero-sized type is passed to `read_volatile`) are noops /// and may be ignored. /// /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf @@ -839,7 +839,7 @@ pub unsafe fn write_unaligned(dst: *mut T, src: T) { /// * `src` must be properly aligned. /// /// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of -/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned +/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned /// value and the value at `*src` can [violate memory safety][read-ownership]. /// However, storing non-[`Copy`] types in volatile memory is almost certainly /// incorrect. @@ -903,7 +903,7 @@ pub unsafe fn read_volatile(src: *const T) -> T { /// /// The compiler shouldn't change the relative order or number of volatile /// memory operations. However, volatile memory operations on zero-sized types -/// (e.g., if a zero-sized type is passed to `write_volatile`) are no-ops +/// (e.g., if a zero-sized type is passed to `write_volatile`) are noops /// and may be ignored. /// /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf @@ -1093,7 +1093,7 @@ impl *const T { /// unless `x` and `y` point into the same allocated object. /// /// Always use `.offset(count)` instead when possible, because `offset` - /// allows the compiler to optimize better. If you need to cross object + /// allows the compiler to optimize better. If you need to cross object /// boundaries, cast the pointer to an integer and do the arithmetic there. /// /// # Examples @@ -1712,7 +1712,7 @@ impl *mut T { /// unless `x` and `y` point into the same allocated object. /// /// Always use `.offset(count)` instead when possible, because `offset` - /// allows the compiler to optimize better. If you need to cross object + /// allows the compiler to optimize better. If you need to cross object /// boundaries, cast the pointer to an integer and do the arithmetic there. /// /// # Examples @@ -2473,7 +2473,7 @@ impl PartialEq for *mut T { #[stable(feature = "rust1", since = "1.0.0")] impl Eq for *mut T {} -/// Compare raw pointers for equality. +/// Compares raw pointers for equality. /// /// This is the same as using the `==` operator, but less generic: /// the arguments have to be `*const T` raw pointers, diff --git a/src/libcore/result.rs b/src/libcore/result.rs index 1ebf0714e23e4..92d29f6ee8a30 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -896,7 +896,7 @@ impl Result { /// /// # Examples /// - /// Convert a string to an integer, turning poorly-formed strings + /// Converts a string to an integer, turning poorly-formed strings /// into 0 (the default value for integers). [`parse`] converts /// a string to any other type that implements [`FromStr`], returning an /// [`Err`] on error. diff --git a/src/libcore/slice/memchr.rs b/src/libcore/slice/memchr.rs index 312838a170c6b..cbba546b8daba 100644 --- a/src/libcore/slice/memchr.rs +++ b/src/libcore/slice/memchr.rs @@ -11,7 +11,7 @@ const HI_U64: u64 = 0x8080808080808080; const LO_USIZE: usize = LO_U64 as usize; const HI_USIZE: usize = HI_U64 as usize; -/// Returns whether `x` contains any zero byte. +/// Returns `true` if `x` contains any zero byte. /// /// From *Matters Computational*, J. Arndt: /// diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs index d062da0c247ad..acca9748372ca 100644 --- a/src/libcore/slice/mod.rs +++ b/src/libcore/slice/mod.rs @@ -1197,7 +1197,7 @@ impl [T] { /// Returns an iterator over subslices separated by elements that match /// `pred` limited to returning at most `n` items. This starts at the end of - /// the slice and works backwards. The matched element is not contained in + /// the slice and works backwards. The matched element is not contained in /// the subslices. /// /// The last element returned, if any, will contain the remainder of the @@ -3145,7 +3145,7 @@ unsafe impl Sync for Iter<'_, T> {} unsafe impl 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 Sync for IterMut<'_, T> {} unsafe impl 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. @@ -4123,7 +4123,7 @@ pub struct ChunksExact<'a, T:'a> { } impl<'a, T> ChunksExact<'a, T> { - /// Return the remainder of the original slice that is not going to be + /// Returns the remainder of the original slice that is not going to be /// returned by the iterator. The returned slice has at most `chunk_size-1` /// elements. #[stable(feature = "chunks_exact", since = "1.31.0")] @@ -4247,7 +4247,7 @@ pub struct ChunksExactMut<'a, T:'a> { } impl<'a, T> ChunksExactMut<'a, T> { - /// Return the remainder of the original slice that is not going to be + /// Returns the remainder of the original slice that is not going to be /// returned by the iterator. The returned slice has at most `chunk_size-1` /// elements. #[stable(feature = "chunks_exact", since = "1.31.0")] @@ -4619,7 +4619,7 @@ pub struct RChunksExact<'a, T:'a> { } impl<'a, T> RChunksExact<'a, T> { - /// Return the remainder of the original slice that is not going to be + /// Returns the remainder of the original slice that is not going to be /// returned by the iterator. The returned slice has at most `chunk_size-1` /// elements. #[stable(feature = "rchunks", since = "1.31.0")] @@ -4744,7 +4744,7 @@ pub struct RChunksExactMut<'a, T:'a> { } impl<'a, T> RChunksExactMut<'a, T> { - /// Return the remainder of the original slice that is not going to be + /// Returns the remainder of the original slice that is not going to be /// returned by the iterator. The returned slice has at most `chunk_size-1` /// elements. #[stable(feature = "rchunks", since = "1.31.0")] diff --git a/src/libcore/slice/rotate.rs b/src/libcore/slice/rotate.rs index 52677713f5ac4..9b35b51349a02 100644 --- a/src/libcore/slice/rotate.rs +++ b/src/libcore/slice/rotate.rs @@ -26,7 +26,7 @@ impl RawArray { } /// Rotates the range `[mid-left, mid+right)` such that the element at `mid` -/// becomes the first element. Equivalently, rotates the range `left` +/// becomes the first element. Equivalently, rotates the range `left` /// elements to the left or `right` elements to the right. /// /// # Safety @@ -36,10 +36,10 @@ impl RawArray { /// # Algorithm /// /// For longer rotations, swap the left-most `delta = min(left, right)` -/// elements with the right-most `delta` elements. LLVM vectorizes this, +/// elements with the right-most `delta` elements. LLVM vectorizes this, /// which is profitable as we only reach this step for a "large enough" -/// rotation. Doing this puts `delta` elements on the larger side into the -/// correct position, leaving a smaller rotate problem. Demonstration: +/// rotation. Doing this puts `delta` elements on the larger side into the +/// correct position, leaving a smaller rotate problem. Demonstration: /// /// ```text /// [ 6 7 8 9 10 11 12 13 . 1 2 3 4 5 ] diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index e9190cc3ddf1b..6c08e545c5c0f 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -1,6 +1,6 @@ -//! String manipulation +//! String manipulation. //! -//! For more details, see std::str +//! For more details, see the `std::str` module. #![stable(feature = "rust1", since = "1.0.0")] @@ -226,7 +226,7 @@ impl Utf8Error { #[stable(feature = "utf8_error", since = "1.5.0")] pub fn valid_up_to(&self) -> usize { self.valid_up_to } - /// Provide more information about the failure: + /// Provides more information about the failure: /// /// * `None`: the end of the input was reached unexpectedly. /// `self.valid_up_to()` is 1 to 3 bytes from the end of the input. @@ -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. @@ -1579,9 +1579,9 @@ mod traits { /// Implements ordering of strings. /// - /// Strings are ordered lexicographically by their byte values. This orders Unicode code - /// points based on their positions in the code charts. This is not necessarily the same as - /// "alphabetical" order, which varies by language and locale. Sorting strings according to + /// Strings are ordered lexicographically by their byte values. This orders Unicode code + /// points based on their positions in the code charts. This is not necessarily the same as + /// "alphabetical" order, which varies by language and locale. Sorting strings according to /// culturally-accepted standards requires locale-specific data that is outside the scope of /// the `str` type. #[stable(feature = "rust1", since = "1.0.0")] @@ -1607,9 +1607,9 @@ mod traits { /// Implements comparison operations on strings. /// - /// Strings are compared lexicographically by their byte values. This compares Unicode code - /// points based on their positions in the code charts. This is not necessarily the same as - /// "alphabetical" order, which varies by language and locale. Comparing strings according to + /// Strings are compared lexicographically by their byte values. This compares Unicode code + /// points based on their positions in the code charts. This is not necessarily the same as + /// "alphabetical" order, which varies by language and locale. Comparing strings according to /// culturally-accepted standards requires locale-specific data that is outside the scope of /// the `str` type. #[stable(feature = "rust1", since = "1.0.0")] @@ -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. @@ -3504,7 +3504,7 @@ impl str { /// /// A string is a sequence of bytes. `start` in this context means the first /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be left side; and for right-to-left languages like + /// Russian, this will be left side, and for right-to-left languages like /// like Arabic or Hebrew, this will be the right side. /// /// # Examples @@ -3541,7 +3541,7 @@ impl str { /// /// A string is a sequence of bytes. `end` in this context means the last /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be right side; and for right-to-left languages like + /// Russian, this will be right side, and for right-to-left languages like /// like Arabic or Hebrew, this will be the left side. /// /// # Examples @@ -3787,7 +3787,7 @@ impl str { /// /// A string is a sequence of bytes. `start` in this context means the first /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be left side; and for right-to-left languages like + /// Russian, this will be left side, and for right-to-left languages like /// like Arabic or Hebrew, this will be the right side. /// /// # Examples @@ -3819,7 +3819,7 @@ impl str { /// /// A string is a sequence of bytes. `end` in this context means the last /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be right side; and for right-to-left languages like + /// Russian, this will be right side, and for right-to-left languages like /// like Arabic or Hebrew, this will be the left side. /// /// # Examples diff --git a/src/libcore/str/pattern.rs b/src/libcore/str/pattern.rs index 55a7ba181e527..2571780ad0bab 100644 --- a/src/libcore/str/pattern.rs +++ b/src/libcore/str/pattern.rs @@ -1,7 +1,7 @@ //! The string Pattern API. //! -//! For more details, see the traits `Pattern`, `Searcher`, -//! `ReverseSearcher` and `DoubleEndedSearcher`. +//! For more details, see the traits [`Pattern`], [`Searcher`], +//! [`ReverseSearcher`], and [`DoubleEndedSearcher`]. #![unstable(feature = "pattern", reason = "API not fully fleshed out and ready to be stabilized", @@ -117,7 +117,7 @@ pub unsafe trait Searcher<'a> { /// `[Reject(0, 1), Reject(1, 2), Match(2, 5), Reject(5, 8)]` fn next(&mut self) -> SearchStep; - /// Find the next `Match` result. See `next()` + /// Finds the next `Match` result. See `next()` /// /// Unlike next(), there is no guarantee that the returned ranges /// of this and next_reject will overlap. This will return (start_match, end_match), @@ -134,7 +134,7 @@ pub unsafe trait Searcher<'a> { } } - /// Find the next `Reject` result. See `next()` and `next_match()` + /// Finds the next `Reject` result. See `next()` and `next_match()` /// /// Unlike next(), there is no guarantee that the returned ranges /// of this and next_match will overlap. @@ -185,7 +185,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> { /// `[Reject(7, 8), Match(4, 7), Reject(1, 4), Reject(0, 1)]` fn next_back(&mut self) -> SearchStep; - /// Find the next `Match` result. See `next_back()` + /// Finds the next `Match` result. See `next_back()` #[inline] fn next_match_back(&mut self) -> Option<(usize, usize)>{ loop { @@ -197,7 +197,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> { } } - /// Find the next `Reject` result. See `next_back()` + /// Finds the next `Reject` result. See `next_back()` #[inline] fn next_reject_back(&mut self) -> Option<(usize, usize)>{ loop { diff --git a/src/libcore/task/poll.rs b/src/libcore/task/poll.rs index ac656153519e1..c811f96ace3ba 100644 --- a/src/libcore/task/poll.rs +++ b/src/libcore/task/poll.rs @@ -22,7 +22,7 @@ pub enum Poll { } impl Poll { - /// Change the ready value of this `Poll` with the closure provided + /// Changes the ready value of this `Poll` with the closure provided. pub fn map(self, f: F) -> Poll where F: FnOnce(T) -> U { @@ -32,7 +32,7 @@ impl Poll { } } - /// Returns whether this is `Poll::Ready` + /// Returns `true` if this is `Poll::Ready` #[inline] pub fn is_ready(&self) -> bool { match *self { @@ -41,7 +41,7 @@ impl Poll { } } - /// Returns whether this is `Poll::Pending` + /// Returns `true` if this is `Poll::Pending` #[inline] pub fn is_pending(&self) -> bool { !self.is_ready() @@ -49,7 +49,7 @@ impl Poll { } impl Poll> { - /// Change the success value of this `Poll` with the closure provided + /// Changes the success value of this `Poll` with the closure provided. pub fn map_ok(self, f: F) -> Poll> where F: FnOnce(T) -> U { @@ -60,7 +60,7 @@ impl Poll> { } } - /// Change the error value of this `Poll` with the closure provided + /// Changes the error value of this `Poll` with the closure provided. pub fn map_err(self, f: F) -> Poll> where F: FnOnce(E) -> U { diff --git a/src/libcore/task/wake.rs b/src/libcore/task/wake.rs index 3f7098f1ef934..6d54989706cac 100644 --- a/src/libcore/task/wake.rs +++ b/src/libcore/task/wake.rs @@ -41,11 +41,11 @@ impl Waker { unsafe { self.inner.as_ref().wake() } } - /// Returns whether or not this `Waker` and `other` awaken the same task. + /// Returns `true` if or not this `Waker` and `other` awaken the same task. /// /// This function works on a best-effort basis, and may return false even /// when the `Waker`s would awaken the same task. However, if this function - /// returns true, it is guaranteed that the `Waker`s will awaken the same + /// returns `true`, it is guaranteed that the `Waker`s will awaken the same /// task. /// /// This function is primarily used for optimization purposes. @@ -54,7 +54,7 @@ impl Waker { self.inner == other.inner } - /// Returns whether or not this `Waker` and `other` `LocalWaker` awaken + /// Returns `true` if or not this `Waker` and `other` `LocalWaker` awaken /// the same task. /// /// This function works on a best-effort basis, and may return false even @@ -150,7 +150,7 @@ impl LocalWaker { unsafe { self.0.inner.as_ref().wake_local() } } - /// Returns whether or not this `LocalWaker` and `other` `LocalWaker` awaken the same task. + /// Returns `true` if or not this `LocalWaker` and `other` `LocalWaker` awaken the same task. /// /// This function works on a best-effort basis, and may return false even /// when the `LocalWaker`s would awaken the same task. However, if this function @@ -163,7 +163,7 @@ impl LocalWaker { self.0.will_wake(&other.0) } - /// Returns whether or not this `LocalWaker` and `other` `Waker` awaken the same task. + /// Returns `true` if or not this `LocalWaker` and `other` `Waker` awaken the same task. /// /// This function works on a best-effort basis, and may return false even /// when the `Waker`s would awaken the same task. However, if this function @@ -223,14 +223,14 @@ pub unsafe trait UnsafeWake: Send + Sync { /// Drops this instance of `UnsafeWake`, deallocating resources /// associated with it. /// - /// FIXME(cramertj) + // FIXME(cramertj): /// This method is intended to have a signature such as: /// /// ```ignore (not-a-doctest) /// fn drop_raw(self: *mut Self); /// ``` /// - /// Unfortunately in Rust today that signature is not object safe. + /// Unfortunately, in Rust today that signature is not object safe. /// Nevertheless it's recommended to implement this function *as if* that /// were its signature. As such it is not safe to call on an invalid /// pointer, nor is the validity of the pointer guaranteed after this diff --git a/src/libcore/tests/iter.rs b/src/libcore/tests/iter.rs index 9b4c78f8d3b02..51a6017de1b5f 100644 --- a/src/libcore/tests/iter.rs +++ b/src/libcore/tests/iter.rs @@ -881,7 +881,7 @@ fn test_iterator_flat_map() { assert_eq!(i, ys.len()); } -/// Test `FlatMap::fold` with items already picked off the front and back, +/// Tests `FlatMap::fold` with items already picked off the front and back, /// to make sure all parts of the `FlatMap` are folded correctly. #[test] fn test_iterator_flat_map_fold() { @@ -919,7 +919,7 @@ fn test_iterator_flatten() { assert_eq!(i, ys.len()); } -/// Test `Flatten::fold` with items already picked off the front and back, +/// Tests `Flatten::fold` with items already picked off the front and back, /// to make sure all parts of the `Flatten` are folded correctly. #[test] fn test_iterator_flatten_fold() { diff --git a/src/libcore/time.rs b/src/libcore/time.rs index a751965dffab3..ac7e11754aa3a 100644 --- a/src/libcore/time.rs +++ b/src/libcore/time.rs @@ -43,7 +43,7 @@ pub const NANOSECOND: Duration = Duration::from_nanos(1); /// timeouts. /// /// Each `Duration` is composed of a whole number of seconds and a fractional part -/// represented in nanoseconds. If the underlying system does not support +/// represented in nanoseconds. If the underlying system does not support /// nanosecond-level precision, APIs binding a system timeout will typically round up /// the number of nanoseconds. /// @@ -515,7 +515,7 @@ impl Duration { } } - /// Multiply `Duration` by `f64`. + /// Multiplies `Duration` by `f64`. /// /// # Panics /// This method will panic if result is not finite, negative or overflows `Duration`. diff --git a/src/libgraphviz/lib.rs b/src/libgraphviz/lib.rs index fadcfaec4b268..7e7a9df93cd7b 100644 --- a/src/libgraphviz/lib.rs +++ b/src/libgraphviz/lib.rs @@ -393,7 +393,7 @@ impl<'a> Id<'a> { /// digit (i.e., the regular expression `[a-zA-Z_][a-zA-Z_0-9]*`). /// /// (Note: this format is a strict subset of the `ID` format - /// defined by the DOT language. This function may change in the + /// defined by the DOT language. This function may change in the /// future to accept a broader subset, or the entirety, of DOT's /// `ID` format.) /// @@ -530,7 +530,7 @@ impl<'a> LabelText<'a> { } /// Decomposes content into string suitable for making EscStr that - /// yields same content as self. The result obeys the law + /// yields same content as self. The result obeys the law /// render(`lt`) == render(`EscStr(lt.pre_escaped_content())`) for /// all `lt: LabelText`. fn pre_escaped_content(self) -> Cow<'a, str> { diff --git a/src/libpanic_unwind/dummy.rs b/src/libpanic_unwind/dummy.rs index b052f76e2a3a8..3a00d6376658c 100644 --- a/src/libpanic_unwind/dummy.rs +++ b/src/libpanic_unwind/dummy.rs @@ -1,6 +1,6 @@ -//! Unwinding for wasm32 +//! Unwinding for *wasm32* target. //! -//! Right now we don't support this, so this is just stubs +//! Right now we don't support this, so this is just stubs. use alloc::boxed::Box; use core::any::Any; diff --git a/src/libpanic_unwind/dwarf/eh.rs b/src/libpanic_unwind/dwarf/eh.rs index ce7fab8584a28..ce24406b55642 100644 --- a/src/libpanic_unwind/dwarf/eh.rs +++ b/src/libpanic_unwind/dwarf/eh.rs @@ -6,7 +6,7 @@ //! http://www.airs.com/blog/archives/464 //! //! A reference implementation may be found in the GCC source tree -//! (/libgcc/unwind-c.c as of this writing) +//! (`/libgcc/unwind-c.c` as of this writing). #![allow(non_upper_case_globals)] #![allow(unused)] diff --git a/src/libpanic_unwind/dwarf/mod.rs b/src/libpanic_unwind/dwarf/mod.rs index eb5fb81f61b83..0360696426dc9 100644 --- a/src/libpanic_unwind/dwarf/mod.rs +++ b/src/libpanic_unwind/dwarf/mod.rs @@ -1,5 +1,5 @@ //! Utilities for parsing DWARF-encoded data streams. -//! See http://www.dwarfstd.org, +//! See , //! DWARF-4 standard, Section 7 - "Data Representation" // This module is used only by x86_64-pc-windows-gnu for now, but we diff --git a/src/libpanic_unwind/emcc.rs b/src/libpanic_unwind/emcc.rs index 45c9244a46fcd..1f5ccfb0f1210 100644 --- a/src/libpanic_unwind/emcc.rs +++ b/src/libpanic_unwind/emcc.rs @@ -1,9 +1,9 @@ -//! Unwinding for emscripten +//! Unwinding for *emscripten* target. //! //! Whereas Rust's usual unwinding implementation for Unix platforms -//! calls into the libunwind APIs directly, on emscripten we instead +//! calls into the libunwind APIs directly, on Emscripten we instead //! call into the C++ unwinding APIs. This is just an expedience since -//! emscripten's runtime always implements those APIs and does not +//! Emscripten's runtime always implements those APIs and does not //! implement libunwind. #![allow(private_no_mangle_fns)] diff --git a/src/libpanic_unwind/gcc.rs b/src/libpanic_unwind/gcc.rs index 065403aba1b98..607fe28e3f28d 100644 --- a/src/libpanic_unwind/gcc.rs +++ b/src/libpanic_unwind/gcc.rs @@ -1,4 +1,4 @@ -//! Implementation of panics backed by libgcc/libunwind (in some form) +//! Implementation of panics backed by libgcc/libunwind (in some form). //! //! For background on exception handling and stack unwinding please see //! "Exception Handling in LLVM" (llvm.org/docs/ExceptionHandling.html) and @@ -23,14 +23,14 @@ //! //! In the search phase, the job of a personality routine is to examine //! exception object being thrown, and to decide whether it should be caught at -//! that stack frame. Once the handler frame has been identified, cleanup phase +//! that stack frame. Once the handler frame has been identified, cleanup phase //! begins. //! //! In the cleanup phase, the unwinder invokes each personality routine again. //! This time it decides which (if any) cleanup code needs to be run for -//! the current stack frame. If so, the control is transferred to a special +//! the current stack frame. If so, the control is transferred to a special //! branch in the function body, the "landing pad", which invokes destructors, -//! frees memory, etc. At the end of the landing pad, control is transferred +//! frees memory, etc. At the end of the landing pad, control is transferred //! back to the unwinder and unwinding resumes. //! //! Once stack has been unwound down to the handler frame level, unwinding stops @@ -39,7 +39,7 @@ //! ## `eh_personality` and `eh_unwind_resume` //! //! These language items are used by the compiler when generating unwind info. -//! The first one is the personality routine described above. The second one +//! The first one is the personality routine described above. The second one //! allows compilation target to customize the process of resuming unwind at the //! end of the landing pads. `eh_unwind_resume` is used only if //! `custom_unwind_resume` flag in the target options is set. diff --git a/src/libproc_macro/bridge/scoped_cell.rs b/src/libproc_macro/bridge/scoped_cell.rs index b1ab27c153e06..6f7965095b638 100644 --- a/src/libproc_macro/bridge/scoped_cell.rs +++ b/src/libproc_macro/bridge/scoped_cell.rs @@ -38,7 +38,7 @@ impl ScopedCell { 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 ScopedCell { 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: >::Out, f: impl FnOnce() -> R) -> R { self.replace(value, |_| f()) } diff --git a/src/libproc_macro/diagnostic.rs b/src/libproc_macro/diagnostic.rs index 7a0c9419f6234..65eebb5ec3737 100644 --- a/src/libproc_macro/diagnostic.rs +++ b/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>(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>(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(spans: S, level: Level, message: T) -> Diagnostic diff --git a/src/libproc_macro/lib.rs b/src/libproc_macro/lib.rs index 09a4a964abf09..238f8f635415b 100644 --- a/src/libproc_macro/lib.rs +++ b/src/libproc_macro/lib.rs @@ -89,7 +89,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 { @@ -245,7 +245,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>(self, message: T) -> Diagnostic { @@ -291,19 +291,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")] @@ -369,7 +369,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 diff --git a/src/librustc/dep_graph/debug.rs b/src/librustc/dep_graph/debug.rs index a9ad22c5e913e..f18ee3dced72d 100644 --- a/src/librustc/dep_graph/debug.rs +++ b/src/librustc/dep_graph/debug.rs @@ -22,7 +22,7 @@ impl DepNodeFilter { } } - /// True if all nodes always pass the filter. + /// Returns `true` if all nodes always pass the filter. pub fn accepts_all(&self) -> bool { self.text.is_empty() } diff --git a/src/librustc/dep_graph/dep_node.rs b/src/librustc/dep_graph/dep_node.rs index 58087b76266b5..796739c872174 100644 --- a/src/librustc/dep_graph/dep_node.rs +++ b/src/librustc/dep_graph/dep_node.rs @@ -302,7 +302,7 @@ macro_rules! define_dep_nodes { } } - /// Create a new, parameterless DepNode. This method will assert + /// Creates a new, parameterless DepNode. This method will assert /// that the DepNode corresponding to the given DepKind actually /// does not require any parameters. #[inline(always)] @@ -314,7 +314,7 @@ macro_rules! define_dep_nodes { } } - /// Extract the DefId corresponding to this DepNode. This will work + /// Extracts the DefId corresponding to this DepNode. This will work /// if two conditions are met: /// /// 1. The Fingerprint of the DepNode actually is a DefPathHash, and @@ -798,7 +798,7 @@ impl<'a, 'gcx: 'tcx + 'a, 'tcx: 'a> DepNodeParams<'a, 'gcx, 'tcx> for HirId { } /// A "work product" corresponds to a `.o` (or other) file that we -/// save in between runs. These ids do not have a DefId but rather +/// save in between runs. These IDs do not have a `DefId` but rather /// some independent path or string that persists between runs without /// the need to be mapped or unmapped. (This ensures we can serialize /// them even in the absence of a tcx.) diff --git a/src/librustc/dep_graph/dep_tracking_map.rs b/src/librustc/dep_graph/dep_tracking_map.rs index a296a3379c2ac..94b832bea628e 100644 --- a/src/librustc/dep_graph/dep_tracking_map.rs +++ b/src/librustc/dep_graph/dep_tracking_map.rs @@ -43,7 +43,7 @@ impl MemoizationMap for RefCell> { /// /// Here, `[op]` represents whatever nodes `op` reads in the /// course of execution; `Map(key)` represents the node for this - /// map; and `CurrentTask` represents the current task when + /// map, and `CurrentTask` represents the current task when /// `memoize` is invoked. /// /// **Important:** when `op` is invoked, the current task will be diff --git a/src/librustc/dep_graph/graph.rs b/src/librustc/dep_graph/graph.rs index e8c1cd36064e1..59ec459de9641 100644 --- a/src/librustc/dep_graph/graph.rs +++ b/src/librustc/dep_graph/graph.rs @@ -61,13 +61,13 @@ struct DepGraphData { colors: DepNodeColorMap, - /// A set of loaded diagnostics which has been emitted. + /// A set of loaded diagnostics that have been emitted. emitted_diagnostics: Mutex>, /// Used to wait for diagnostics to be emitted. emitted_diagnostics_cond_var: Condvar, - /// When we load, there may be `.o` files, cached mir, or other such + /// When we load, there may be `.o` files, cached MIR, or other such /// things available to us. If we find that they are not dirty, we /// load the path to the file storing those work-products here into /// this map. We can later look for and extract that data. @@ -115,7 +115,7 @@ impl DepGraph { } } - /// True if we are actually building the full dep-graph. + /// Returns `true` if we are actually building the full dep-graph, and `false` otherwise. #[inline] pub fn is_fully_enabled(&self) -> bool { self.data.is_some() @@ -320,8 +320,8 @@ impl DepGraph { } } - /// Execute something within an "anonymous" task, that is, a task the - /// DepNode of which is determined by the list of inputs it read from. + /// Executes something within an "anonymous" task, that is, a task the + /// `DepNode` of which is determined by the list of inputs it read from. pub fn with_anon_task(&self, dep_kind: DepKind, op: OP) -> (R, DepNodeIndex) where OP: FnOnce() -> R { @@ -356,8 +356,8 @@ impl DepGraph { } } - /// Execute something within an "eval-always" task which is a task - // that runs whenever anything changes. + /// Executes something within an "eval-always" task which is a task + /// that runs whenever anything changes. pub fn with_eval_always_task<'a, C, A, R>( &self, key: DepNode, @@ -438,7 +438,7 @@ impl DepGraph { self.data.as_ref().unwrap().previous.node_to_index(dep_node) } - /// Check whether a previous work product exists for `v` and, if + /// Checks whether a previous work product exists for `v` and, if /// so, return the path that leads to it. Used to skip doing work. pub fn previous_work_product(&self, v: &WorkProductId) -> Option { self.data @@ -589,7 +589,7 @@ impl DepGraph { } } - /// Try to mark a dep-node which existed in the previous compilation session as green + /// Try to mark a dep-node which existed in the previous compilation session as green. fn try_mark_previous_green<'tcx>( &self, tcx: TyCtxt<'_, 'tcx, 'tcx>, @@ -773,8 +773,8 @@ impl DepGraph { Some(dep_node_index) } - /// Atomically emits some loaded diagnotics assuming that this only gets called with - /// did_allocation set to true on one thread + /// Atomically emits some loaded diagnotics, assuming that this only gets called with + /// `did_allocation` set to `true` on a single thread. #[cold] #[inline(never)] fn emit_diagnostics<'tcx>( @@ -913,7 +913,7 @@ impl DepGraph { #[derive(Clone, Debug, RustcEncodable, RustcDecodable)] pub struct WorkProduct { pub cgu_name: String, - /// Saved files associated with this CGU + /// Saved files associated with this CGU. pub saved_files: Vec<(WorkProductFileKind, String)>, } @@ -937,17 +937,17 @@ pub(super) struct CurrentDepGraph { #[allow(dead_code)] forbidden_edge: Option, - // Anonymous DepNodes are nodes the ID of which we compute from the list of - // their edges. This has the beneficial side-effect that multiple anonymous - // nodes can be coalesced into one without changing the semantics of the - // dependency graph. However, the merging of nodes can lead to a subtle - // problem during red-green marking: The color of an anonymous node from - // the current session might "shadow" the color of the node with the same - // ID from the previous session. In order to side-step this problem, we make - // sure that anon-node IDs allocated in different sessions don't overlap. - // This is implemented by mixing a session-key into the ID fingerprint of - // each anon node. The session-key is just a random number generated when - // the DepGraph is created. + /// Anonymous `DepNode`s are nodes whose IDs we compute from the list of + /// their edges. This has the beneficial side-effect that multiple anonymous + /// nodes can be coalesced into one without changing the semantics of the + /// dependency graph. However, the merging of nodes can lead to a subtle + /// problem during red-green marking: The color of an anonymous node from + /// the current session might "shadow" the color of the node with the same + /// ID from the previous session. In order to side-step this problem, we make + /// sure that anonymous `NodeId`s allocated in different sessions don't overlap. + /// This is implemented by mixing a session-key into the ID fingerprint of + /// each anon node. The session-key is just a random number generated when + /// the `DepGraph` is created. anon_id_seed: Fingerprint, total_read_count: u64, diff --git a/src/librustc/hir/check_attr.rs b/src/librustc/hir/check_attr.rs index ba340ad251f2a..ddc1eebe645ae 100644 --- a/src/librustc/hir/check_attr.rs +++ b/src/librustc/hir/check_attr.rs @@ -91,7 +91,7 @@ struct CheckAttrVisitor<'a, 'tcx: 'a> { } impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> { - /// Check any attribute. + /// Checks any attribute. fn check_attributes(&self, item: &hir::Item, target: Target) { if target == Target::Fn || target == Target::Const { self.tcx.codegen_fn_attrs(self.tcx.hir().local_def_id(item.id)); @@ -115,7 +115,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> { self.check_used(item, target); } - /// Check if an `#[inline]` is applied to a function or a closure. + /// Checks if an `#[inline]` is applied to a function or a closure. fn check_inline(&self, attr: &hir::Attribute, span: &Span, target: Target) { if target != Target::Fn && target != Target::Closure { struct_span_err!(self.tcx.sess, @@ -127,7 +127,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> { } } - /// Check if the `#[non_exhaustive]` attribute on an `item` is valid. + /// Checks if the `#[non_exhaustive]` attribute on an `item` is valid. fn check_non_exhaustive(&self, attr: &hir::Attribute, item: &hir::Item, target: Target) { match target { Target::Struct | Target::Enum => { /* Valid */ }, @@ -143,7 +143,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> { } } - /// Check if the `#[marker]` attribute on an `item` is valid. + /// Checks if the `#[marker]` attribute on an `item` is valid. fn check_marker(&self, attr: &hir::Attribute, item: &hir::Item, target: Target) { match target { Target::Trait => { /* Valid */ }, @@ -157,7 +157,7 @@ impl<'a, 'tcx> CheckAttrVisitor<'a, 'tcx> { } } - /// Check if the `#[repr]` attributes on `item` are valid. + /// Checks if the `#[repr]` attributes on `item` are valid. fn check_repr(&self, item: &hir::Item, target: Target) { // Extract the names of all repr hints, e.g., [foo, bar, align] for: // ``` diff --git a/src/librustc/hir/def.rs b/src/librustc/hir/def.rs index 15efa7650293c..b15bea017762e 100644 --- a/src/librustc/hir/def.rs +++ b/src/librustc/hir/def.rs @@ -182,7 +182,7 @@ impl ::std::ops::IndexMut for PerNS { } impl PerNS> { - /// Returns whether all the items in this collection are `None`. + /// Returns `true` if all the items in this collection are `None`. pub fn is_empty(&self) -> bool { self.type_ns.is_none() && self.value_ns.is_none() && self.macro_ns.is_none() } diff --git a/src/librustc/hir/def_id.rs b/src/librustc/hir/def_id.rs index e06f09e21cbf3..ed1c15a73c260 100644 --- a/src/librustc/hir/def_id.rs +++ b/src/librustc/hir/def_id.rs @@ -229,7 +229,7 @@ impl fmt::Debug for DefId { } impl DefId { - /// Make a local `DefId` with the given index. + /// Makes a local `DefId` from the given `DefIndex`. #[inline] pub fn local(index: DefIndex) -> DefId { DefId { krate: LOCAL_CRATE, index: index } diff --git a/src/librustc/hir/intravisit.rs b/src/librustc/hir/intravisit.rs index 86c3fb9e4fcd7..9436c600c9fd3 100644 --- a/src/librustc/hir/intravisit.rs +++ b/src/librustc/hir/intravisit.rs @@ -4,7 +4,7 @@ //! `super::itemlikevisit::ItemLikeVisitor` trait.** //! //! If you have decided to use this visitor, here are some general -//! notes on how to do it: +//! notes on how to do so: //! //! Each overridden visit method has full control over what //! happens with its node, it can do its own traversal of the node's children, @@ -86,7 +86,7 @@ pub enum NestedVisitorMap<'this, 'tcx: 'this> { /// using this setting. OnlyBodies(&'this Map<'tcx>), - /// Visit all nested things, including item-likes. + /// Visits all nested things, including item-likes. /// /// **This is an unusual choice.** It is used when you want to /// process everything within their lexical context. Typically you @@ -96,7 +96,7 @@ pub enum NestedVisitorMap<'this, 'tcx: 'this> { impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> { /// Returns the map to use for an "intra item-like" thing (if any). - /// e.g., function body. + /// E.g., function body. pub fn intra(self) -> Option<&'this Map<'tcx>> { match self { NestedVisitorMap::None => None, @@ -106,7 +106,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> { } /// Returns the map to use for an "item-like" thing (if any). - /// e.g., item, impl-item. + /// E.g., item, impl-item. pub fn inter(self) -> Option<&'this Map<'tcx>> { match self { NestedVisitorMap::None => None, @@ -117,7 +117,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> { } /// Each method of the Visitor trait is a hook to be potentially -/// overridden. Each method's default implementation recursively visits +/// overridden. Each method's default implementation recursively visits /// the substructure of the input via the corresponding `walk` method; /// e.g., the `visit_mod` method by default calls `intravisit::walk_mod`. /// @@ -129,7 +129,7 @@ impl<'this, 'tcx> NestedVisitorMap<'this, 'tcx> { /// on `visit_nested_item` for details on how to visit nested items. /// /// If you want to ensure that your code handles every variant -/// explicitly, you need to override each method. (And you also need +/// explicitly, you need to override each method. (And you also need /// to monitor future changes to `Visitor` in case a new method with a /// new default implementation gets introduced.) pub trait Visitor<'v> : Sized { @@ -203,7 +203,7 @@ pub trait Visitor<'v> : Sized { } } - /// Visit the top-level item and (optionally) nested items / impl items. See + /// Visits the top-level item and (optionally) nested items / impl items. See /// `visit_nested_item` for details. fn visit_item(&mut self, i: &'v Item) { walk_item(self, i) @@ -214,7 +214,7 @@ pub trait Visitor<'v> : Sized { } /// When invoking `visit_all_item_likes()`, you need to supply an - /// item-like visitor. This method converts a "intra-visit" + /// item-like visitor. This method converts a "intra-visit" /// visitor into an item-like visitor that walks the entire tree. /// If you use this, you probably don't want to process the /// contents of nested item-like things, since the outer loop will diff --git a/src/librustc/hir/lowering.rs b/src/librustc/hir/lowering.rs index 43c756def88be..6ff4db750044a 100644 --- a/src/librustc/hir/lowering.rs +++ b/src/librustc/hir/lowering.rs @@ -3,24 +3,24 @@ //! Since the AST and HIR are fairly similar, this is mostly a simple procedure, //! much like a fold. Where lowering involves a bit more work things get more //! interesting and there are some invariants you should know about. These mostly -//! concern spans and ids. +//! concern spans and IDs. //! //! Spans are assigned to AST nodes during parsing and then are modified during //! expansion to indicate the origin of a node and the process it went through -//! being expanded. Ids are assigned to AST nodes just before lowering. +//! being expanded. IDs are assigned to AST nodes just before lowering. //! -//! For the simpler lowering steps, ids and spans should be preserved. Unlike +//! For the simpler lowering steps, IDs and spans should be preserved. Unlike //! expansion we do not preserve the process of lowering in the spans, so spans //! should not be modified here. When creating a new node (as opposed to -//! 'folding' an existing one), then you create a new id using `next_id()`. +//! 'folding' an existing one), then you create a new ID using `next_id()`. //! -//! You must ensure that ids are unique. That means that you should only use the -//! id from an AST node in a single HIR node (you can assume that AST node ids -//! are unique). Every new node must have a unique id. Avoid cloning HIR nodes. -//! If you do, you must then set the new node's id to a fresh one. +//! You must ensure that IDs are unique. That means that you should only use the +//! ID from an AST node in a single HIR node (you can assume that AST node IDs +//! are unique). Every new node must have a unique ID. Avoid cloning HIR nodes. +//! If you do, you must then set the new node's ID to a fresh one. //! //! Spans are used for error messages and for tools to map semantics back to -//! source code. It is therefore not as important with spans as ids to be strict +//! source code. It is therefore not as important with spans as IDs to be strict //! about use (you can't break the compiler by screwing up a span). Obviously, a //! HIR node can only have a single span. But multiple nodes can have the same //! span and spans don't need to be kept in order, etc. Where code is preserved @@ -145,7 +145,7 @@ pub trait Resolver { is_value: bool, ) -> hir::Path; - /// Obtain the resolution for a node-id. + /// Obtain the resolution for a `NodeId`. fn get_resolution(&mut self, id: NodeId) -> Option; /// Obtain the possible resolutions for the given `use` statement. @@ -274,10 +274,10 @@ enum ParenthesizedGenericArgs { } /// What to do when we encounter an **anonymous** lifetime -/// reference. Anonymous lifetime references come in two flavors. You +/// reference. Anonymous lifetime references come in two flavors. You /// have implicit, or fully elided, references to lifetimes, like the /// one in `&T` or `Ref`, and you have `'_` lifetimes, like `&'_ T` -/// or `Ref<'_, T>`. These often behave the same, but not always: +/// or `Ref<'_, T>`. These often behave the same, but not always: /// /// - certain usages of implicit references are deprecated, like /// `Ref`, and we sometimes just give hard errors in those cases @@ -3302,7 +3302,7 @@ impl<'a> LoweringContext<'a> { /// Paths like the visibility path in `pub(super) use foo::{bar, baz}` are repeated /// many times in the HIR tree; for each occurrence, we need to assign distinct - /// node-ids. (See e.g., #56128.) + /// `NodeId`s. (See, e.g., #56128.) fn renumber_segment_ids(&mut self, path: &P) -> P { debug!("renumber_segment_ids(path = {:?})", path); let mut path = path.clone(); diff --git a/src/librustc/hir/map/blocks.rs b/src/librustc/hir/map/blocks.rs index d5fb578d8d492..6919628c76755 100644 --- a/src/librustc/hir/map/blocks.rs +++ b/src/librustc/hir/map/blocks.rs @@ -1,9 +1,9 @@ //! This module provides a simplified abstraction for working with -//! code blocks identified by their integer node-id. In particular, +//! code blocks identified by their integer `NodeId`. In particular, //! it captures a common set of attributes that all "function-like -//! things" (represented by `FnLike` instances) share. For example, +//! things" (represented by `FnLike` instances) share. For example, //! all `FnLike` instances have a type signature (be it explicit or -//! inferred). And all `FnLike` instances have a body, i.e., the code +//! inferred). And all `FnLike` instances have a body, i.e., the code //! that is run when the function-like thing it represents is invoked. //! //! With the above abstraction in place, one can treat the program diff --git a/src/librustc/hir/map/def_collector.rs b/src/librustc/hir/map/def_collector.rs index 02fb503e752b5..8fe10a85ef380 100644 --- a/src/librustc/hir/map/def_collector.rs +++ b/src/librustc/hir/map/def_collector.rs @@ -12,7 +12,7 @@ use syntax_pos::Span; use crate::hir::map::{ITEM_LIKE_SPACE, REGULAR_SPACE}; -/// Creates def ids for nodes in the AST. +/// Creates `DefId`s for nodes in the AST. pub struct DefCollector<'a> { definitions: &'a mut Definitions, parent_def: Option, diff --git a/src/librustc/hir/map/definitions.rs b/src/librustc/hir/map/definitions.rs index 84e9cde6df160..f454d691d4188 100644 --- a/src/librustc/hir/map/definitions.rs +++ b/src/librustc/hir/map/definitions.rs @@ -1,5 +1,5 @@ -//! For each definition, we track the following data. A definition -//! here is defined somewhat circularly as "something with a def-id", +//! For each definition, we track the following data. A definition +//! here is defined somewhat circularly as "something with a `DefId`", //! but it generally corresponds to things like structs, enums, etc. //! There are also some rather random cases (like const initializer //! expressions) that are mostly just leftovers. @@ -163,10 +163,10 @@ pub struct Definitions { /// any) with a `DisambiguatedDefPathData`. #[derive(Clone, PartialEq, Debug, Hash, RustcEncodable, RustcDecodable)] pub struct DefKey { - /// Parent path. + /// The parent path. pub parent: Option, - /// Identifier of this node. + /// The identifier of this node. pub disambiguated_data: DisambiguatedDefPathData, } @@ -207,12 +207,12 @@ impl DefKey { } } -/// Pair of `DefPathData` and an integer disambiguator. The integer is +/// A pair of `DefPathData` and an integer disambiguator. The integer is /// normally 0, but in the event that there are multiple defs with the /// same `parent` and `data`, we use this field to disambiguate /// between them. This introduces some artificial ordering dependency /// but means that if you have (e.g.) two impls for the same type in -/// the same module, they do get distinct def-ids. +/// the same module, they do get distinct `DefId`s. #[derive(Clone, PartialEq, Debug, Hash, RustcEncodable, RustcDecodable)] pub struct DisambiguatedDefPathData { pub data: DefPathData, @@ -221,10 +221,10 @@ pub struct DisambiguatedDefPathData { #[derive(Clone, Debug, Hash, RustcEncodable, RustcDecodable)] pub struct DefPath { - /// the path leading from the crate root to the item + /// The path leading from the crate root to the item. pub data: Vec, - /// what krate root is this path relative to? + /// The crate root this path is relative to. pub krate: CrateNum, } @@ -260,9 +260,9 @@ impl DefPath { DefPath { data: data, krate: krate } } - /// Returns a string representation of the DefPath without + /// Returns a string representation of the `DefPath` without /// the crate-prefix. This method is useful if you don't have - /// a TyCtxt available. + /// a `TyCtxt` available. pub fn to_string_no_crate(&self) -> String { let mut s = String::with_capacity(self.data.len() * 16); @@ -277,7 +277,7 @@ impl DefPath { s } - /// Return filename friendly string of the DefPah with the + /// Returns a filename-friendly string for the `DefPath`, with the /// crate-prefix. pub fn to_string_friendly(&self, crate_imported_name: F) -> String where F: FnOnce(CrateNum) -> Symbol @@ -302,9 +302,9 @@ impl DefPath { s } - /// Return filename friendly string of the DefPah without + /// Returns a filename-friendly string of the `DefPath`, without /// the crate-prefix. This method is useful if you don't have - /// a TyCtxt available. + /// a `TyCtxt` available. pub fn to_filename_friendly_no_crate(&self) -> String { let mut s = String::with_capacity(self.data.len() * 16); @@ -394,18 +394,18 @@ impl Borrow for DefPathHash { } impl Definitions { - /// Create new empty definition map. + /// Creates new empty definition map. /// - /// The DefIndex returned from a new Definitions are as follows: - /// 1. At DefIndexAddressSpace::Low, + /// The `DefIndex` returned from a new `Definitions` are as follows: + /// 1. At `DefIndexAddressSpace::Low`, /// CRATE_ROOT has index 0:0, and then new indexes are allocated in /// ascending order. - /// 2. At DefIndexAddressSpace::High, - /// the first FIRST_FREE_HIGH_DEF_INDEX indexes are reserved for - /// internal use, then 1:FIRST_FREE_HIGH_DEF_INDEX are allocated in + /// 2. At `DefIndexAddressSpace::High`, + /// the first `FIRST_FREE_HIGH_DEF_INDEX` indexes are reserved for + /// internal use, then `1:FIRST_FREE_HIGH_DEF_INDEX` are allocated in /// ascending order. - /// - /// FIXME: there is probably a better place to put this comment. + // + // FIXME: there is probably a better place to put this comment. pub fn new() -> Self { Self::default() } @@ -414,7 +414,7 @@ impl Definitions { &self.table } - /// Get the number of definitions. + /// Gets the number of definitions. pub fn def_index_counts_lo_hi(&self) -> (usize, usize) { (self.table.index_to_key[DefIndexAddressSpace::Low.index()].len(), self.table.index_to_key[DefIndexAddressSpace::High.index()].len()) @@ -497,8 +497,8 @@ impl Definitions { self.node_to_hir_id[node_id] } - /// Retrieve the span of the given `DefId` if `DefId` is in the local crate, the span exists and - /// it's not DUMMY_SP + /// Retrieves the span of the given `DefId` if `DefId` is in the local crate, the span exists + /// and it's not `DUMMY_SP`. #[inline] pub fn opt_span(&self, def_id: DefId) -> Option { if def_id.krate == LOCAL_CRATE { @@ -508,7 +508,7 @@ impl Definitions { } } - /// Add a definition with a parent definition. + /// Adds a root definition (no parent). pub fn create_root_def(&mut self, crate_name: &str, crate_disambiguator: CrateDisambiguator) @@ -606,7 +606,7 @@ impl Definitions { index } - /// Initialize the ast::NodeId to HirId mapping once it has been generated during + /// Initialize the `ast::NodeId` to `HirId` mapping once it has been generated during /// AST to HIR lowering. pub fn init_node_id_to_hir_id_mapping(&mut self, mapping: IndexVec) { diff --git a/src/librustc/hir/map/mod.rs b/src/librustc/hir/map/mod.rs index 2bf82180779d9..692b7fd37d28d 100644 --- a/src/librustc/hir/map/mod.rs +++ b/src/librustc/hir/map/mod.rs @@ -36,7 +36,7 @@ mod hir_id_validator; pub const ITEM_LIKE_SPACE: DefIndexAddressSpace = DefIndexAddressSpace::Low; pub const REGULAR_SPACE: DefIndexAddressSpace = DefIndexAddressSpace::High; -/// Represents an entry and its parent NodeId. +/// Represents an entry and its parent `NodeId`. #[derive(Copy, Clone, Debug)] pub struct Entry<'hir> { parent: NodeId, @@ -162,8 +162,7 @@ impl Forest { } } -/// Represents a mapping from Node IDs to AST elements and their parent -/// Node IDs +/// Represents a mapping from `NodeId`s to AST elements and their parent `NodeId`s. #[derive(Clone)] pub struct Map<'hir> { /// The backing storage for all the AST nodes. @@ -473,7 +472,7 @@ impl<'hir> Map<'hir> { self.local_def_id(self.body_owner(id)) } - /// Given a node id, returns the `BodyId` associated with it, + /// Given a `NodeId`, returns the `BodyId` associated with it, /// if the node is a body owner, otherwise returns `None`. pub fn maybe_body_owned_by(&self, id: NodeId) -> Option { if let Some(entry) = self.find_entry(id) { @@ -558,7 +557,7 @@ impl<'hir> Map<'hir> { self.trait_auto_impl(trait_did).is_some() } - /// Get the attributes on the krate. This is preferable to + /// Gets the attributes on the crate. This is preferable to /// invoking `krate.attrs` because it registers a tighter /// dep-graph access. pub fn krate_attrs(&self) -> &'hir [ast::Attribute] { @@ -653,8 +652,7 @@ impl<'hir> Map<'hir> { self.get_generics(id).map(|generics| generics.span).filter(|sp| *sp != DUMMY_SP) } - /// Retrieve the Node corresponding to `id`, returning None if - /// cannot be found. + /// Retrieves the `Node` corresponding to `id`, returning `None` if cannot be found. pub fn find(&self, id: NodeId) -> Option> { let result = self.find_entry(id).and_then(|entry| { if let Node::Crate = entry.node { @@ -683,8 +681,8 @@ impl<'hir> Map<'hir> { /// returns the enclosing item. Note that this might not be the actual parent /// node in the AST - some kinds of nodes are not in the map and these will /// never appear as the parent_node. So you can always walk the `parent_nodes` - /// from a node to the root of the ast (unless you get the same id back here - /// that can happen if the id is not in the map itself or is just weird). + /// from a node to the root of the ast (unless you get the same ID back here + /// that can happen if the ID is not in the map itself or is just weird). pub fn get_parent_node(&self, id: NodeId) -> NodeId { if self.dep_graph.is_fully_enabled() { let hir_id_owner = self.node_to_hir_id(id).owner; @@ -725,7 +723,7 @@ impl<'hir> Map<'hir> { /// If there is some error when walking the parents (e.g., a node does not /// have a parent in the map or a node can't be found), then we return the - /// last good node id we found. Note that reaching the crate root (`id == 0`), + /// last good `NodeId` we found. Note that reaching the crate root (`id == 0`), /// is not an error, since items in the crate module have the crate root as /// parent. fn walk_parent_nodes(&self, @@ -761,7 +759,7 @@ impl<'hir> Map<'hir> { } } - /// Retrieve the `NodeId` for `id`'s enclosing method, unless there's a + /// Retrieves the `NodeId` for `id`'s enclosing method, unless there's a /// `while` or `loop` before reaching it, as block tail returns are not /// available in them. /// @@ -809,7 +807,7 @@ impl<'hir> Map<'hir> { self.walk_parent_nodes(id, match_fn, match_non_returning_block).ok() } - /// Retrieve the `NodeId` for `id`'s parent item, or `id` itself if no + /// Retrieves the `NodeId` for `id`'s parent item, or `id` itself if no /// parent item is in this map. The "parent item" is the closest parent node /// in the HIR which is recorded by the map and is an item, either an item /// in a module, trait, or impl. @@ -1126,7 +1124,7 @@ pub struct NodesMatchingSuffix<'a, 'hir:'a> { } impl<'a, 'hir> NodesMatchingSuffix<'a, 'hir> { - /// Returns true only if some suffix of the module path for parent + /// Returns `true` only if some suffix of the module path for parent /// matches `self.in_which`. /// /// In other words: let `[x_0,x_1,...,x_k]` be `self.in_which`; diff --git a/src/librustc/hir/mod.rs b/src/librustc/hir/mod.rs index 3e7dd1432e1e3..d9759da9dfca8 100644 --- a/src/librustc/hir/mod.rs +++ b/src/librustc/hir/mod.rs @@ -62,14 +62,14 @@ pub mod map; pub mod pat_util; pub mod print; -/// A HirId uniquely identifies a node in the HIR of the current crate. It is -/// composed of the `owner`, which is the DefIndex of the directly enclosing -/// hir::Item, hir::TraitItem, or hir::ImplItem (i.e., the closest "item-like"), +/// Uniquely identifies a node in the HIR of the current crate. It is +/// composed of the `owner`, which is the `DefIndex` of the directly enclosing +/// `hir::Item`, `hir::TraitItem`, or `hir::ImplItem` (i.e., the closest "item-like"), /// and the `local_id` which is unique within the given owner. /// /// This two-level structure makes for more stable values: One can move an item /// around within the source code, or add or remove stuff before it, without -/// the local_id part of the HirId changing, which is a very useful property in +/// the `local_id` part of the `HirId` changing, which is a very useful property in /// incremental compilation where we have to persist things through changes to /// the code base. #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)] @@ -130,7 +130,7 @@ mod item_local_id_inner { pub use self::item_local_id_inner::ItemLocalId; -/// The `HirId` corresponding to CRATE_NODE_ID and CRATE_DEF_INDEX +/// The `HirId` corresponding to `CRATE_NODE_ID` and `CRATE_DEF_INDEX`. pub const CRATE_HIR_ID: HirId = HirId { owner: CRATE_DEF_INDEX, local_id: ItemLocalId::from_u32_const(0) @@ -149,8 +149,8 @@ pub struct Lifetime { pub hir_id: HirId, pub span: Span, - /// Either "'a", referring to a named lifetime definition, - /// or "" (aka keywords::Invalid), for elision placeholders. + /// Either "`'a`", referring to a named lifetime definition, + /// or "``" (i.e., `keywords::Invalid`), for elision placeholders. /// /// HIR lowering inserts these placeholders in type paths that /// refer to type definitions needing lifetime parameters, @@ -163,8 +163,9 @@ pub enum ParamName { /// Some user-given name like `T` or `'x`. Plain(Ident), - /// Synthetic name generated when user elided a lifetime in an impl header, - /// e.g., the lifetimes in cases like these: + /// Synthetic name generated when user elided a lifetime in an impl header. + /// + /// E.g., the lifetimes in cases like these: /// /// impl Foo for &u32 /// impl Foo<'_> for u32 @@ -180,7 +181,7 @@ pub enum ParamName { /// Indicates an illegal name was given and an error has been /// repored (so we should squelch other derived errors). Occurs - /// when e.g., `'_` is used in the wrong place. + /// when, e.g., `'_` is used in the wrong place. Error, } @@ -205,17 +206,17 @@ pub enum LifetimeName { /// User-given names or fresh (synthetic) names. Param(ParamName), - /// User typed nothing. e.g., the lifetime in `&u32`. + /// User wrote nothing (e.g., the lifetime in `&u32`). Implicit, /// Indicates an error during lowering (usually `'_` in wrong place) /// that was already reported. Error, - /// User typed `'_`. + /// User wrote specifies `'_`. Underscore, - /// User wrote `'static` + /// User wrote `'static`. Static, } @@ -280,7 +281,7 @@ impl Lifetime { } } -/// A "Path" is essentially Rust's notion of a name; for instance: +/// A `Path` is essentially Rust's notion of a name; for instance, /// `std::cmp::PartialEq`. It's represented as a sequence of identifiers, /// along with a bunch of supporting information. #[derive(Clone, RustcEncodable, RustcDecodable)] @@ -340,7 +341,7 @@ pub struct PathSegment { } impl PathSegment { - /// Convert an identifier to the corresponding segment. + /// Converts an identifier to the corresponding segment. pub fn from_ident(ident: Ident) -> PathSegment { PathSegment { ident, @@ -597,14 +598,14 @@ impl Generics { } } -/// Synthetic Type Parameters are converted to an other form during lowering, this allows -/// to track the original form they had. Useful for error messages. +/// Synthetic type parameters are converted to another form during lowering; this allows +/// us to track the original form they had, and is useful for error messages. #[derive(Copy, Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)] pub enum SyntheticTyParamKind { ImplTrait } -/// A `where` clause in a definition +/// A where-clause in a definition. #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct WhereClause { pub id: NodeId, @@ -624,7 +625,7 @@ impl WhereClause { } } -/// A single predicate in a `where` clause +/// A single predicate in a where-clause. #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub enum WherePredicate { /// A type binding (e.g., `for<'c> Foo: Send + Clone + 'c`). @@ -645,19 +646,19 @@ impl WherePredicate { } } -/// A type bound, eg `for<'c> Foo: Send+Clone+'c` +/// A type bound (e.g., `for<'c> Foo: Send + Clone + 'c`). #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct WhereBoundPredicate { pub span: Span, - /// Any generics from a `for` binding + /// Any generics from a `for` binding. pub bound_generic_params: HirVec, - /// The type being bounded + /// The type being bounded. pub bounded_ty: P, - /// Trait and lifetime bounds (`Clone+Send+'static`) + /// Trait and lifetime bounds (e.g., `Clone + Send + 'static`). pub bounds: GenericBounds, } -/// A lifetime predicate, e.g., `'a: 'b+'c` +/// A lifetime predicate (e.g., `'a: 'b + 'c`). #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct WhereRegionPredicate { pub span: Span, @@ -665,7 +666,7 @@ pub struct WhereRegionPredicate { pub bounds: GenericBounds, } -/// An equality predicate (unsupported), e.g., `T=int` +/// An equality predicate (e.g., `T = int`); currently unsupported. #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct WhereEqPredicate { pub id: NodeId, @@ -759,7 +760,7 @@ impl Crate { } } - /// A parallel version of visit_all_item_likes + /// A parallel version of `visit_all_item_likes`. pub fn par_visit_all_item_likes<'hir, V>(&'hir self, visitor: &V) where V: itemlikevisit::ParItemLikeVisitor<'hir> + Sync + Send { @@ -800,14 +801,14 @@ pub struct MacroDef { #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct Block { - /// Statements in a block + /// Statements in a block. pub stmts: HirVec, /// An expression at the end of the block - /// without a semicolon, if any + /// without a semicolon, if any. pub expr: Option>, pub id: NodeId, pub hir_id: HirId, - /// Distinguishes between `unsafe { ... }` and `{ ... }` + /// Distinguishes between `unsafe { ... }` and `{ ... }`. pub rules: BlockCheckMode, pub span: Span, /// If true, then there may exist `break 'a` values that aim to @@ -874,18 +875,18 @@ impl Pat { } } -/// A single field in a struct pattern +/// A single field in a struct pattern. /// /// Patterns like the fields of Foo `{ x, ref y, ref mut z }` /// are treated the same as` x: x, y: ref y, z: ref mut z`, -/// except is_shorthand is true +/// except `is_shorthand` is true. #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct FieldPat { pub id: NodeId, pub hir_id: HirId, - /// The identifier for the field + /// The identifier for the field. pub ident: Ident, - /// The pattern the field is destructured to + /// The pattern the field is destructured to. pub pat: P, pub is_shorthand: bool, } @@ -922,41 +923,41 @@ pub enum RangeEnd { #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub enum PatKind { - /// Represents a wildcard pattern (`_`) + /// Represents a wildcard pattern (i.e., `_`). Wild, /// A fresh binding `ref mut binding @ OPT_SUBPATTERN`. /// The `NodeId` is the canonical ID for the variable being bound, - /// e.g., in `Ok(x) | Err(x)`, both `x` use the same canonical ID, + /// (e.g., in `Ok(x) | Err(x)`, both `x` use the same canonical ID), /// which is the pattern ID of the first `x`. Binding(BindingAnnotation, NodeId, HirId, Ident, Option>), - /// A struct or struct variant pattern, e.g., `Variant {x, y, ..}`. + /// A struct or struct variant pattern (e.g., `Variant {x, y, ..}`). /// The `bool` is `true` in the presence of a `..`. Struct(QPath, HirVec>, bool), /// A tuple struct/variant pattern `Variant(x, y, .., z)`. /// If the `..` pattern fragment is present, then `Option` denotes its position. - /// 0 <= position <= subpats.len() + /// `0 <= position <= subpats.len()` TupleStruct(QPath, HirVec>, Option), /// A path pattern for an unit struct/variant or a (maybe-associated) constant. Path(QPath), - /// A tuple pattern `(a, b)`. + /// A tuple pattern (e.g., `(a, b)`). /// If the `..` pattern fragment is present, then `Option` denotes its position. - /// 0 <= position <= subpats.len() + /// `0 <= position <= subpats.len()` Tuple(HirVec>, Option), - /// A `box` pattern + /// A `box` pattern. Box(P), - /// A reference pattern, e.g., `&mut (a, b)` + /// A reference pattern (e.g., `&mut (a, b)`). Ref(P, Mutability), - /// A literal + /// A literal. Lit(P), - /// A range pattern, e.g., `1...2` or `1..2` + /// A range pattern (e.g., `1...2` or `1..2`). Range(P, P, RangeEnd), /// `[a, b, ..i, y, z]` is represented as: - /// `PatKind::Slice(box [a, b], Some(i), box [y, z])` + /// `PatKind::Slice(box [a, b], Some(i), box [y, z])`. Slice(HirVec>, Option>, HirVec>), } @@ -967,7 +968,7 @@ pub enum Mutability { } impl Mutability { - /// Return MutMutable only if both arguments are mutable. + /// Returns `MutMutable` only if both arguments are mutable. pub fn and(self, other: Self) -> Self { match self { MutMutable => other, @@ -978,41 +979,41 @@ impl Mutability { #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable, Debug, Copy, Hash)] pub enum BinOpKind { - /// The `+` operator (addition) + /// The `+` operator (addition). Add, - /// The `-` operator (subtraction) + /// The `-` operator (subtraction). Sub, - /// The `*` operator (multiplication) + /// The `*` operator (multiplication). Mul, - /// The `/` operator (division) + /// The `/` operator (division). Div, - /// The `%` operator (modulus) + /// The `%` operator (modulus). Rem, - /// The `&&` operator (logical and) + /// The `&&` operator (logical and). And, - /// The `||` operator (logical or) + /// The `||` operator (logical or). Or, - /// The `^` operator (bitwise xor) + /// The `^` operator (bitwise xor). BitXor, - /// The `&` operator (bitwise and) + /// The `&` operator (bitwise and). BitAnd, - /// The `|` operator (bitwise or) + /// The `|` operator (bitwise or). BitOr, - /// The `<<` operator (shift left) + /// The `<<` operator (shift left). Shl, - /// The `>>` operator (shift right) + /// The `>>` operator (shift right). Shr, - /// The `==` operator (equality) + /// The `==` operator (equality). Eq, - /// The `<` operator (less than) + /// The `<` operator (less than). Lt, - /// The `<=` operator (less than or equal to) + /// The `<=` operator (less than or equal to). Le, - /// The `!=` operator (not equal to) + /// The `!=` operator (not equal to). Ne, - /// The `>=` operator (greater than or equal to) + /// The `>=` operator (greater than or equal to). Ge, - /// The `>` operator (greater than) + /// The `>` operator (greater than). Gt, } @@ -1077,7 +1078,7 @@ impl BinOpKind { } } - /// Returns `true` if the binary operator takes its arguments by value + /// Returns `true` if the binary operator takes its arguments by value. pub fn is_by_value(self) -> bool { !self.is_comparison() } @@ -1112,11 +1113,11 @@ pub type BinOp = Spanned; #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable, Debug, Copy, Hash)] pub enum UnOp { - /// The `*` operator for dereferencing + /// The `*` operator (deferencing). UnDeref, - /// The `!` operator for logical inversion + /// The `!` operator (logical negation). UnNot, - /// The `-` operator for negation + /// The `-` operator (negation). UnNeg, } @@ -1129,7 +1130,7 @@ impl UnOp { } } - /// Returns `true` if the unary operator takes its argument by value + /// Returns `true` if the unary operator takes its argument by value. pub fn is_by_value(self) -> bool { match self { UnNeg | UnNot => true, @@ -1138,7 +1139,7 @@ impl UnOp { } } -/// A statement +/// A statement. #[derive(Clone, RustcEncodable, RustcDecodable)] pub struct Stmt { pub id: NodeId, @@ -1156,15 +1157,15 @@ impl fmt::Debug for Stmt { #[derive(Clone, RustcEncodable, RustcDecodable)] pub enum StmtKind { - /// A local (let) binding: + /// A local (`let`) binding. Local(P), - /// An item binding: + /// An item binding. Item(P), - /// Expr without trailing semi-colon (must have unit type): + /// An expression without a trailing semi-colon (must have unit type). Expr(P), - /// Expr with trailing semi-colon (may have any type): + /// An expression with a trailing semi-colon (may have any type). Semi(P), } @@ -1179,12 +1180,12 @@ impl StmtKind { } } -/// Local represents a `let` statement, e.g., `let : = ;` +/// Represents a `let` statement (i.e., `let : = ;`). #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct Local { pub pat: P, pub ty: Option>, - /// Initializer expression to set the value, if any + /// Initializer expression to set the value, if any. pub init: Option>, pub id: NodeId, pub hir_id: HirId, @@ -1193,7 +1194,7 @@ pub struct Local { pub source: LocalSource, } -/// represents one arm of a 'match' +/// Represents a single arm of a `match` expression. #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct Arm { pub attrs: HirVec, @@ -1419,16 +1420,16 @@ impl fmt::Debug for Expr { pub enum ExprKind { /// A `box x` expression. Box(P), - /// An array (`[a, b, c, d]`) + /// An array (e.g., `[a, b, c, d]`). Array(HirVec), - /// A function call + /// A function call. /// /// The first field resolves to the function itself (usually an `ExprKind::Path`), /// and the second field is the list of arguments. /// This also represents calling the constructor of /// tuple-like ADTs such as tuple structs and enum variants. Call(P, HirVec), - /// A method call (`x.foo::<'static, Bar, Baz>(a, b, c, d)`) + /// A method call (e.g., `x.foo::<'static, Bar, Baz>(a, b, c, d)`). /// /// The `PathSegment`/`Span` represent the method name and its generic arguments /// (within the angle brackets). @@ -1438,63 +1439,64 @@ pub enum ExprKind { /// Thus, `x.foo::(a, b, c, d)` is represented as /// `ExprKind::MethodCall(PathSegment { foo, [Bar, Baz] }, [x, a, b, c, d])`. MethodCall(PathSegment, Span, HirVec), - /// A tuple (`(a, b, c ,d)`) + /// A tuple (e.g., `(a, b, c ,d)`). Tup(HirVec), - /// A binary operation (For example: `a + b`, `a * b`) + /// A binary operation (e.g., `a + b`, `a * b`). Binary(BinOp, P, P), - /// A unary operation (For example: `!x`, `*x`) + /// A unary operation (e.g., `!x`, `*x`). Unary(UnOp, P), - /// A literal (For example: `1`, `"foo"`) + /// A literal (e.g., `1`, `"foo"`). Lit(Lit), - /// A cast (`foo as f64`) + /// A cast (e.g., `foo as f64`). Cast(P, P), + /// A type reference (e.g., `Foo`). Type(P, P), - /// An `if` block, with an optional else block + /// An `if` block, with an optional else block. /// - /// `if expr { expr } else { expr }` + /// I.e., `if { } else { }`. If(P, P, Option>), /// A while loop, with an optional label /// - /// `'label: while expr { block }` + /// I.e., `'label: while expr { }`. While(P, P, Option

(&mut self, processor: &mut P, do_completed: DoCompleted) -> Outcome where P: ObligationProcessor @@ -461,7 +461,7 @@ impl ObligationForest { } } - /// Mark all NodeState::Success nodes as NodeState::Done and + /// Mark all `NodeState::Success` nodes as `NodeState::Done` and /// report all cycles between them. This should be called /// after `mark_as_waiting` marks all nodes with pending /// subobligations as NodeState::Waiting. @@ -566,7 +566,7 @@ impl ObligationForest { } } - /// Marks all nodes that depend on a pending node as NodeState::Waiting. + /// Marks all nodes that depend on a pending node as `NodeState::Waiting`. fn mark_as_waiting(&self) { for node in &self.nodes { if node.state.get() == NodeState::Waiting { diff --git a/src/librustc_data_structures/owning_ref/mod.rs b/src/librustc_data_structures/owning_ref/mod.rs index 30e510cc5b055..236559dcd7c10 100644 --- a/src/librustc_data_structures/owning_ref/mod.rs +++ b/src/librustc_data_structures/owning_ref/mod.rs @@ -286,7 +286,7 @@ impl Erased for T {} pub unsafe trait IntoErased<'a> { /// Owner with the dereference type substituted to `Erased`. type Erased; - /// Perform the type erasure. + /// Performs the type erasure. fn into_erased(self) -> Self::Erased; } @@ -296,7 +296,7 @@ pub unsafe trait IntoErased<'a> { pub unsafe trait IntoErasedSend<'a> { /// Owner with the dereference type substituted to `Erased + Send`. type Erased: Send; - /// Perform the type erasure. + /// Performs the type erasure. fn into_erased_send(self) -> Self::Erased; } @@ -306,7 +306,7 @@ pub unsafe trait IntoErasedSend<'a> { pub unsafe trait IntoErasedSendSync<'a> { /// Owner with the dereference type substituted to `Erased + Send + Sync`. type Erased: Send + Sync; - /// Perform the type erasure. + /// Performs the type erasure. fn into_erased_send_sync(self) -> Self::Erased; } @@ -844,7 +844,7 @@ pub trait ToHandleMut { impl OwningHandle where O: StableAddress, O::Target: ToHandle, H: Deref, { - /// Create a new `OwningHandle` for a type that implements `ToHandle`. For types + /// Creates a new `OwningHandle` for a type that implements `ToHandle`. For types /// that don't implement `ToHandle`, callers may invoke `new_with_fn`, which accepts /// a callback to perform the conversion. pub fn new(o: O) -> Self { @@ -855,7 +855,7 @@ impl OwningHandle impl OwningHandle where O: StableAddress, O::Target: ToHandleMut, H: DerefMut, { - /// Create a new mutable `OwningHandle` for a type that implements `ToHandleMut`. + /// Creates a new mutable `OwningHandle` for a type that implements `ToHandleMut`. pub fn new_mut(o: O) -> Self { OwningHandle::new_with_fn(o, |x| unsafe { O::Target::to_handle_mut(x) }) } @@ -864,7 +864,7 @@ impl OwningHandle impl OwningHandle where O: StableAddress, H: Deref, { - /// Create a new OwningHandle. The provided callback will be invoked with + /// Creates a new OwningHandle. The provided callback will be invoked with /// a pointer to the object owned by `o`, and the returned value is stored /// as the object to which this `OwningHandle` will forward `Deref` and /// `DerefMut`. @@ -882,7 +882,7 @@ impl OwningHandle } } - /// Create a new OwningHandle. The provided callback will be invoked with + /// Creates a new OwningHandle. The provided callback will be invoked with /// a pointer to the object owned by `o`, and the returned value is stored /// as the object to which this `OwningHandle` will forward `Deref` and /// `DerefMut`. diff --git a/src/librustc_data_structures/sip128.rs b/src/librustc_data_structures/sip128.rs index 9ec9a39840032..06f157f972932 100644 --- a/src/librustc_data_structures/sip128.rs +++ b/src/librustc_data_structures/sip128.rs @@ -44,7 +44,7 @@ macro_rules! compress { }); } -/// Load an integer of the desired type from a byte stream, in LE order. Uses +/// Loads an integer of the desired type from a byte stream, in LE order. Uses /// `copy_nonoverlapping` to let the compiler generate the most efficient way /// to load it from a possibly unaligned address. /// @@ -61,7 +61,7 @@ macro_rules! load_int_le { }); } -/// Load an u64 using up to 7 bytes of a byte slice. +/// Loads an u64 using up to 7 bytes of a byte slice. /// /// Unsafe because: unchecked indexing at start..start+len #[inline] diff --git a/src/librustc_data_structures/svh.rs b/src/librustc_data_structures/svh.rs index 3757f921098f2..df4f61768375e 100644 --- a/src/librustc_data_structures/svh.rs +++ b/src/librustc_data_structures/svh.rs @@ -17,7 +17,7 @@ pub struct Svh { } impl Svh { - /// Create a new `Svh` given the hash. If you actually want to + /// Creates a new `Svh` given the hash. If you actually want to /// compute the SVH from some HIR, you want the `calculate_svh` /// function found in `librustc_incremental`. pub fn new(hash: u64) -> Svh { diff --git a/src/librustc_data_structures/transitive_relation.rs b/src/librustc_data_structures/transitive_relation.rs index 39aed9833607f..0974607fabea8 100644 --- a/src/librustc_data_structures/transitive_relation.rs +++ b/src/librustc_data_structures/transitive_relation.rs @@ -82,7 +82,7 @@ impl TransitiveRelation { } /// Applies the (partial) function to each edge and returns a new - /// relation. If `f` returns `None` for any end-point, returns + /// relation. If `f` returns `None` for any end-point, returns /// `None`. pub fn maybe_map(&self, mut f: F) -> Option> where F: FnMut(&T) -> Option, @@ -111,7 +111,7 @@ impl TransitiveRelation { } } - /// Check whether `a < target` (transitively) + /// Checks whether `a < target` (transitively) pub fn contains(&self, a: &T, b: &T) -> bool { match (self.index(a), self.index(b)) { (Some(a), Some(b)) => self.with_closure(|closure| closure.contains(a.0, b.0)), @@ -122,7 +122,7 @@ impl TransitiveRelation { /// Thinking of `x R y` as an edge `x -> y` in a graph, this /// returns all things reachable from `a`. /// - /// Really this probably ought to be `impl Iterator`, but + /// Really this probably ought to be `impl Iterator`, but /// I'm too lazy to make that work, and -- given the caching /// strategy -- it'd be a touch tricky anyhow. pub fn reachable_from(&self, a: &T) -> Vec<&T> { @@ -152,20 +152,20 @@ impl TransitiveRelation { /// the query is `postdom_upper_bound(a, b)`: /// /// ```text - /// // returns Some(x), which is also LUB + /// // Returns Some(x), which is also LUB. /// a -> a1 -> x /// ^ /// | /// b -> b1 ---+ /// - /// // returns Some(x), which is not LUB (there is none) - /// // diagonal edges run left-to-right + /// // Returns `Some(x)`, which is not LUB (there is none) + /// // diagonal edges run left-to-right. /// a -> a1 -> x /// \/ ^ /// /\ | /// b -> b1 ---+ /// - /// // returns None + /// // Returns `None`. /// a -> a1 /// b -> b1 /// ``` diff --git a/src/librustc_data_structures/work_queue.rs b/src/librustc_data_structures/work_queue.rs index 06418b1051ac3..193025aafad20 100644 --- a/src/librustc_data_structures/work_queue.rs +++ b/src/librustc_data_structures/work_queue.rs @@ -14,7 +14,7 @@ pub struct WorkQueue { } impl WorkQueue { - /// Create a new work queue with all the elements from (0..len). + /// Creates a new work queue with all the elements from (0..len). #[inline] pub fn with_all(len: usize) -> Self { WorkQueue { @@ -23,7 +23,7 @@ impl WorkQueue { } } - /// Create a new work queue that starts empty, where elements range from (0..len). + /// Creates a new work queue that starts empty, where elements range from (0..len). #[inline] pub fn with_none(len: usize) -> Self { WorkQueue { @@ -54,7 +54,7 @@ impl WorkQueue { } } - /// True if nothing is enqueued. + /// Returns `true` if nothing is enqueued. #[inline] pub fn is_empty(&self) -> bool { self.deque.is_empty() diff --git a/src/librustc_driver/driver.rs b/src/librustc_driver/driver.rs index 6a23cadf87795..09804a706ec98 100644 --- a/src/librustc_driver/driver.rs +++ b/src/librustc_driver/driver.rs @@ -711,7 +711,7 @@ pub struct InnerExpansionResult<'a> { pub hir_forest: hir_map::Forest, } -/// Run the "early phases" of the compiler: initial `cfg` processing, +/// Runs the "early phases" of the compiler: initial `cfg` processing, /// loading compiler plugins (including those from `addl_plugins`), /// syntax expansion, secondary `cfg` expansion, synthesis of a test /// harness if one is to be provided, injection of a dependency on the @@ -1167,7 +1167,7 @@ pub fn default_provide_extern(providers: &mut ty::query::Providers) { cstore::provide_extern(providers); } -/// Run the resolution, typechecking, region checking and other +/// Runs the resolution, typec-hecking, region checking and other /// miscellaneous analysis passes on the crate. Return various /// structures carrying the results of the analysis. pub fn phase_3_run_analysis_passes<'tcx, F, R>( @@ -1334,7 +1334,7 @@ where ) } -/// Run the codegen backend, after which the AST and analysis can +/// Runs the codegen backend, after which the AST and analysis can /// be discarded. pub fn phase_4_codegen<'a, 'tcx>( codegen_backend: &dyn CodegenBackend, diff --git a/src/librustc_driver/lib.rs b/src/librustc_driver/lib.rs index f34a7e040b1c3..990ad4ada01a2 100644 --- a/src/librustc_driver/lib.rs +++ b/src/librustc_driver/lib.rs @@ -114,7 +114,7 @@ pub mod target_features { use rustc::session::Session; use rustc_codegen_utils::codegen_backend::CodegenBackend; - /// Add `target_feature = "..."` cfgs for a variety of platform + /// Adds `target_feature = "..."` cfgs for a variety of platform /// specific features (SSE, NEON etc.). /// /// This is performed by checking whether a whitelisted set of @@ -1324,7 +1324,7 @@ fn print_flag_list(cmdline_opt: &str, /// Process command line options. Emits messages as appropriate. If compilation /// should continue, returns a getopts::Matches object parsed from args, -/// otherwise returns None. +/// otherwise returns `None`. /// /// The compiler's handling of options is a little complicated as it ties into /// our stability story, and it's even *more* complicated by historical @@ -1488,7 +1488,7 @@ pub fn in_rustc_thread(f: F) -> Result> in_named_rustc_thread("rustc".to_string(), f) } -/// Get a list of extra command-line flags provided by the user, as strings. +/// Gets a list of extra command-line flags provided by the user, as strings. /// /// This function is used during ICEs to show more information useful for /// debugging, since some ICEs only happens with non-default compiler flags @@ -1553,7 +1553,7 @@ impl Display for CompilationFailure { } } -/// Run a procedure which will detect panics in the compiler and print nicer +/// Runs a procedure which will detect panics in the compiler and print nicer /// error messages rather than just failing the test. /// /// The diagnostic emitter yielded to the procedure should be used for reporting diff --git a/src/librustc_driver/test.rs b/src/librustc_driver/test.rs index afcf08632a4f0..2ec755bd62691 100644 --- a/src/librustc_driver/test.rs +++ b/src/librustc_driver/test.rs @@ -1,4 +1,4 @@ -//! # Standalone Tests for the Inference Module +//! Standalone tests for the inference module. use driver; use errors; @@ -508,8 +508,8 @@ fn subst_ty_renumber_bound() { }) } -/// Test substituting a bound region into a function, which introduces another level of binding. -/// This requires adjusting the Debruijn index. +/// Tests substituting a bound region into a function, which introduces another level of binding. +/// This requires adjusting the De Bruijn index. #[test] fn subst_ty_renumber_some_bounds() { test_env(EMPTY_SOURCE_STR, errors(&[]), |env| { @@ -544,7 +544,7 @@ fn subst_ty_renumber_some_bounds() { }) } -/// Test that we correctly compute whether a type has escaping regions or not. +/// Tests that we correctly compute whether a type has escaping regions or not. #[test] fn escaping() { test_env(EMPTY_SOURCE_STR, errors(&[]), |mut env| { @@ -571,7 +571,7 @@ fn escaping() { }) } -/// Test applying a substitution where the value being substituted for an early-bound region is a +/// Tests applying a substitution where the value being substituted for an early-bound region is a /// late-bound region. #[test] fn subst_region_renumber_region() { diff --git a/src/librustc_errors/diagnostic.rs b/src/librustc_errors/diagnostic.rs index aefe296ad0fa7..2c410f69bfc66 100644 --- a/src/librustc_errors/diagnostic.rs +++ b/src/librustc_errors/diagnostic.rs @@ -118,7 +118,7 @@ impl Diagnostic { self.level == Level::Cancelled } - /// Add a span/label to be included in the resulting snippet. + /// Adds a span/label to be included in the resulting snippet. /// This is pushed onto the `MultiSpan` that was created when the /// diagnostic was first built. If you don't call this function at /// all, and you just supplied a `Span` to create the diagnostic, diff --git a/src/librustc_errors/diagnostic_builder.rs b/src/librustc_errors/diagnostic_builder.rs index fd4ea7f2d823f..9d5e8d10b1772 100644 --- a/src/librustc_errors/diagnostic_builder.rs +++ b/src/librustc_errors/diagnostic_builder.rs @@ -26,7 +26,7 @@ pub struct DiagnosticBuilder<'a> { /// In general, the `DiagnosticBuilder` uses deref to allow access to /// the fields and methods of the embedded `diagnostic` in a -/// transparent way. *However,* many of the methods are intended to +/// transparent way. *However,* many of the methods are intended to /// be used in a chained way, and hence ought to return `self`. In /// that case, we can't just naively forward to the method on the /// `diagnostic`, because the return type would be a `&Diagnostic` @@ -150,7 +150,7 @@ impl<'a> DiagnosticBuilder<'a> { self.cancel(); } - /// Add a span/label to be included in the resulting snippet. + /// Adds a span/label to be included in the resulting snippet. /// This is pushed onto the `MultiSpan` that was created when the /// diagnostic was first built. If you don't call this function at /// all, and you just supplied a `Span` to create the diagnostic, diff --git a/src/librustc_errors/emitter.rs b/src/librustc_errors/emitter.rs index 2821201173ea0..1c0c9d137e40f 100644 --- a/src/librustc_errors/emitter.rs +++ b/src/librustc_errors/emitter.rs @@ -22,7 +22,7 @@ pub trait Emitter { /// Emit a structured diagnostic. fn emit(&mut self, db: &DiagnosticBuilder<'_>); - /// Check if should show explanations about "rustc --explain" + /// Checks if should show explanations about "rustc --explain" fn should_show_explain(&self) -> bool { true } @@ -868,7 +868,7 @@ impl EmitterWriter { } } - /// Add a left margin to every line but the first, given a padding length and the label being + /// Adds a left margin to every line but the first, given a padding length and the label being /// displayed, keeping the provided highlighting. fn msg_to_buffer(&self, buffer: &mut StyledBuffer, @@ -895,7 +895,7 @@ impl EmitterWriter { // `max_line_num_len` let padding = " ".repeat(padding + label.len() + 5); - /// Return whether `style`, or the override if present and the style is `NoStyle`. + /// Returns `true` if `style`, or the override if present and the style is `NoStyle`. fn style_or_override(style: Style, override_style: Option