nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-04-28 11:07:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix doc nits

Browse Source 
Many tiny changes to stdlib doc comments to make them consistent (for example
"Returns foo", rather than "Return foo", per RFC1574), adding missing periods, paragraph
breaks, backticks for monospace style, and other minor nits.

https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
This commit is contained in:
John Arundel 2024-07-15 12:26:30 +01:00
parent 83d67685ac
commit a19472a93e
146 changed files with 808 additions and 738 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
library/alloc/src/alloc.rs
View File

@ -57,7 +57,7 @@ pub struct Global;
#[cfg(test)] #[cfg(test)]
pub use std::alloc::Global; pub use std::alloc::Global;
/// Allocate memory with the global allocator. /// Allocates memory with the global allocator.
/// ///
/// This function forwards calls to the [`GlobalAlloc::alloc`] method /// This function forwards calls to the [`GlobalAlloc::alloc`] method
/// of the allocator registered with the `#[global_allocator]` attribute /// of the allocator registered with the `#[global_allocator]` attribute
@ -101,7 +101,7 @@ pub unsafe fn alloc(layout: Layout) -> *mut u8 {
} }
} }
/// Deallocate memory with the global allocator. /// Deallocates memory with the global allocator.
/// ///
/// This function forwards calls to the [`GlobalAlloc::dealloc`] method /// This function forwards calls to the [`GlobalAlloc::dealloc`] method
/// of the allocator registered with the `#[global_allocator]` attribute /// of the allocator registered with the `#[global_allocator]` attribute
@ -119,7 +119,7 @@ pub unsafe fn dealloc(ptr: *mut u8, layout: Layout) {
unsafe { __rust_dealloc(ptr, layout.size(), layout.align()) } unsafe { __rust_dealloc(ptr, layout.size(), layout.align()) }
} }
/// Reallocate memory with the global allocator. /// Reallocates memory with the global allocator.
/// ///
/// This function forwards calls to the [`GlobalAlloc::realloc`] method /// This function forwards calls to the [`GlobalAlloc::realloc`] method
/// of the allocator registered with the `#[global_allocator]` attribute /// of the allocator registered with the `#[global_allocator]` attribute
@ -138,7 +138,7 @@ pub unsafe fn realloc(ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8
unsafe { __rust_realloc(ptr, layout.size(), layout.align(), new_size) } unsafe { __rust_realloc(ptr, layout.size(), layout.align(), new_size) }
} }
/// Allocate zero-initialized memory with the global allocator. /// Allocates zero-initialized memory with the global allocator.
/// ///
/// This function forwards calls to the [`GlobalAlloc::alloc_zeroed`] method /// This function forwards calls to the [`GlobalAlloc::alloc_zeroed`] method
/// of the allocator registered with the `#[global_allocator]` attribute /// of the allocator registered with the `#[global_allocator]` attribute
@ -345,7 +345,7 @@ extern "Rust" {
fn __rust_alloc_error_handler(size: usize, align: usize) -> !; fn __rust_alloc_error_handler(size: usize, align: usize) -> !;
} }
/// Signal a memory allocation error. /// Signals a memory allocation error.
/// ///
/// Callers of memory allocation APIs wishing to cease execution /// Callers of memory allocation APIs wishing to cease execution
/// in response to an allocation error are encouraged to call this function, /// in response to an allocation error are encouraged to call this function,

14
library/alloc/src/boxed.rs
View File

@ -1268,9 +1268,11 @@ impl<T: ?Sized, A: Allocator> Box<T, A> {
} }
/// Consumes and leaks the `Box`, returning a mutable reference, /// Consumes and leaks the `Box`, returning a mutable reference,
/// `&'a mut T`. Note that the type `T` must outlive the chosen lifetime /// `&'a mut T`.
/// `'a`. If the type has only static references, or none at all, then this ///
/// may be chosen to be `'static`. /// Note that the type `T` must outlive the chosen lifetime `'a`. If the type
/// has only static references, or none at all, then this may be chosen to be
/// `'static`.
/// ///
/// This function is mainly useful for data that lives for the remainder of /// This function is mainly useful for data that lives for the remainder of
/// the program's life. Dropping the returned reference will cause a memory /// the program's life. Dropping the returned reference will cause a memory
@ -1853,7 +1855,7 @@ impl<T, const N: usize> TryFrom<Vec<T>> for Box<[T; N]> {
} }
impl<A: Allocator> Box<dyn Any, A> { impl<A: Allocator> Box<dyn Any, A> {
/// Attempt to downcast the box to a concrete type. /// Attempts to downcast the box to a concrete type.
/// ///
/// # Examples /// # Examples
/// ///
@ -1912,7 +1914,7 @@ impl<A: Allocator> Box<dyn Any, A> {
} }
impl<A: Allocator> Box<dyn Any + Send, A> { impl<A: Allocator> Box<dyn Any + Send, A> {
/// Attempt to downcast the box to a concrete type. /// Attempts to downcast the box to a concrete type.
/// ///
/// # Examples /// # Examples
/// ///
@ -1971,7 +1973,7 @@ impl<A: Allocator> Box<dyn Any + Send, A> {
} }
impl<A: Allocator> Box<dyn Any + Send + Sync, A> { impl<A: Allocator> Box<dyn Any + Send + Sync, A> {
/// Attempt to downcast the box to a concrete type. /// Attempts to downcast the box to a concrete type.
/// ///
/// # Examples /// # Examples
/// ///

3
library/alloc/src/collections/binary_heap/mod.rs
View File

@ -965,6 +965,7 @@ impl<T, A: Allocator> BinaryHeap<T, A> {
} }
/// Returns an iterator which retrieves elements in heap order. /// Returns an iterator which retrieves elements in heap order.
///
/// This method consumes the original heap. /// This method consumes the original heap.
/// ///
/// # Examples /// # Examples
@ -1361,7 +1362,7 @@ struct Hole<'a, T: 'a> {
} }
impl<'a, T> Hole<'a, T> { impl<'a, T> Hole<'a, T> {
/// Create a new `Hole` at index `pos`. /// Creates a new `Hole` at index `pos`.
/// ///
/// Unsafe because pos must be within the data slice. /// Unsafe because pos must be within the data slice.
#[inline] #[inline]

1
library/alloc/src/collections/btree/map/entry.rs
View File

@ -189,6 +189,7 @@ impl<'a, K: Ord, V, A: Allocator + Clone> Entry<'a, K, V, A> {
} }
/// Ensures a value is in the entry by inserting, if empty, the result of the default function. /// Ensures a value is in the entry by inserting, if empty, the result of the default function.
///
/// This method allows for generating key-derived values for insertion by providing the default /// This method allows for generating key-derived values for insertion by providing the default
/// function a reference to the key that was moved during the `.entry(key)` method call. /// function a reference to the key that was moved during the `.entry(key)` method call.
/// ///

3
library/alloc/src/fmt.rs
View File

@ -600,8 +600,7 @@ pub use core::fmt::{LowerHex, Pointer, UpperHex};
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
use crate::string; use crate::string;
/// The `format` function takes an [`Arguments`] struct and returns the resulting /// Takes an [`Arguments`] struct and returns the resulting formatted string.
/// formatted string.
/// ///
/// The [`Arguments`] instance can be created with the [`format_args!`] macro. /// The [`Arguments`] instance can be created with the [`format_args!`] macro.
/// ///

6
library/alloc/src/raw_vec.rs
View File

@ -52,7 +52,7 @@ impl Cap {
/// * Produces `Unique::dangling()` on zero-length allocations. /// * Produces `Unique::dangling()` on zero-length allocations.
/// * Avoids freeing `Unique::dangling()`. /// * Avoids freeing `Unique::dangling()`.
/// * Catches all overflows in capacity computations (promotes them to "capacity overflow" panics). /// * Catches all overflows in capacity computations (promotes them to "capacity overflow" panics).
/// * Guards against 32-bit systems allocating more than isize::MAX bytes. /// * Guards against 32-bit systems allocating more than `isize::MAX` bytes.
/// * Guards against overflowing your length. /// * Guards against overflowing your length.
/// * Calls `handle_alloc_error` for fallible allocations. /// * Calls `handle_alloc_error` for fallible allocations.
/// * Contains a `ptr::Unique` and thus endows the user with all related benefits. /// * Contains a `ptr::Unique` and thus endows the user with all related benefits.
@ -484,7 +484,7 @@ impl<T, A: Allocator> RawVec<T, A> {
// `finish_grow` is non-generic over `T`. // `finish_grow` is non-generic over `T`.
let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?; let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?;
// SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than isize::MAX items // SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than `isize::MAX` items
unsafe { self.set_ptr_and_cap(ptr, cap) }; unsafe { self.set_ptr_and_cap(ptr, cap) };
Ok(()) Ok(())
} }
@ -504,7 +504,7 @@ impl<T, A: Allocator> RawVec<T, A> {
// `finish_grow` is non-generic over `T`. // `finish_grow` is non-generic over `T`.
let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?; let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?;
// SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than isize::MAX items // SAFETY: `finish_grow` would have resulted in a capacity overflow if we tried to allocate more than `isize::MAX` items
unsafe { unsafe {
self.set_ptr_and_cap(ptr, cap); self.set_ptr_and_cap(ptr, cap);
} }

22
library/alloc/src/rc.rs
View File

@ -439,7 +439,7 @@ impl<T> Rc<T> {
/// } /// }
/// ///
/// impl Gadget { /// impl Gadget {
/// /// Construct a reference counted Gadget. /// /// Constructs a reference counted Gadget.
/// fn new() -> Rc<Self> { /// fn new() -> Rc<Self> {
/// // `me` is a `Weak<Gadget>` pointing at the new allocation of the /// // `me` is a `Weak<Gadget>` pointing at the new allocation of the
/// // `Rc` we're constructing. /// // `Rc` we're constructing.
@ -449,7 +449,7 @@ impl<T> Rc<T> {
/// }) /// })
/// } /// }
/// ///
/// /// Return a reference counted pointer to Self. /// /// Returns a reference counted pointer to Self.
/// fn me(&self) -> Rc<Self> { /// fn me(&self) -> Rc<Self> {
/// self.me.upgrade().unwrap() /// self.me.upgrade().unwrap()
/// } /// }
@ -1900,7 +1900,7 @@ impl<T: Clone, A: Allocator> Rc<T, A> {
} }
impl<A: Allocator> Rc<dyn Any, A> { impl<A: Allocator> Rc<dyn Any, A> {
/// Attempt to downcast the `Rc<dyn Any>` to a concrete type. /// Attempts to downcast the `Rc<dyn Any>` to a concrete type.
/// ///
/// # Examples /// # Examples
/// ///
@ -2586,7 +2586,7 @@ impl<T, const N: usize> From<[T; N]> for Rc<[T]> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T: Clone> From<&[T]> for Rc<[T]> { impl<T: Clone> From<&[T]> for Rc<[T]> {
/// Allocate a reference-counted slice and fill it by cloning `v`'s items. /// Allocates a reference-counted slice and fills it by cloning `v`'s items.
/// ///
/// # Example /// # Example
/// ///
@ -2605,7 +2605,7 @@ impl<T: Clone> From<&[T]> for Rc<[T]> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl From<&str> for Rc<str> { impl From<&str> for Rc<str> {
/// Allocate a reference-counted string slice and copy `v` into it. /// Allocates a reference-counted string slice and copies `v` into it.
/// ///
/// # Example /// # Example
/// ///
@ -2624,7 +2624,7 @@ impl From<&str> for Rc<str> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl From<String> for Rc<str> { impl From<String> for Rc<str> {
/// Allocate a reference-counted string slice and copy `v` into it. /// Allocates a reference-counted string slice and copies `v` into it.
/// ///
/// # Example /// # Example
/// ///
@ -2662,7 +2662,7 @@ impl<T: ?Sized, A: Allocator> From<Box<T, A>> for Rc<T, A> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T, A: Allocator> From<Vec<T, A>> for Rc<[T], A> { impl<T, A: Allocator> From<Vec<T, A>> for Rc<[T], A> {
/// Allocate a reference-counted slice and move `v`'s items into it. /// Allocates a reference-counted slice and moves `v`'s items into it.
/// ///
/// # Example /// # Example
/// ///
@ -2695,8 +2695,8 @@ where
B: ToOwned + ?Sized, B: ToOwned + ?Sized,
Rc<B>: From<&'a B> + From<B::Owned>, Rc<B>: From<&'a B> + From<B::Owned>,
{ {
/// Create a reference-counted pointer from /// Creates a reference-counted pointer from a clone-on-write pointer by
/// a clone-on-write pointer by copying its content. /// copying its content.
/// ///
/// # Example /// # Example
/// ///
@ -3526,7 +3526,7 @@ impl<T: ?Sized, A: Allocator> AsRef<T> for Rc<T, A> {
#[stable(feature = "pin", since = "1.33.0")] #[stable(feature = "pin", since = "1.33.0")]
impl<T: ?Sized, A: Allocator> Unpin for Rc<T, A> {} impl<T: ?Sized, A: Allocator> Unpin for Rc<T, A> {}
/// Get the offset within an `RcBox` for the payload behind a pointer. /// Gets the offset within an `RcBox` for the payload behind a pointer.
/// ///
/// # Safety /// # Safety
/// ///
@ -3734,7 +3734,7 @@ struct UniqueRcUninit<T: ?Sized, A: Allocator> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
impl<T: ?Sized, A: Allocator> UniqueRcUninit<T, A> { impl<T: ?Sized, A: Allocator> UniqueRcUninit<T, A> {
/// Allocate a RcBox with layout suitable to contain `for_value` or a clone of it. /// Allocates a RcBox with layout suitable to contain `for_value` or a clone of it.
fn new(for_value: &T, alloc: A) -> UniqueRcUninit<T, A> { fn new(for_value: &T, alloc: A) -> UniqueRcUninit<T, A> {
let layout = Layout::for_value(for_value); let layout = Layout::for_value(for_value);
let ptr = unsafe { let ptr = unsafe {

24
library/alloc/src/sync.rs
View File

@ -428,7 +428,7 @@ impl<T> Arc<T> {
/// } /// }
/// ///
/// impl Gadget { /// impl Gadget {
/// /// Construct a reference counted Gadget. /// /// Constructs a reference counted Gadget.
/// fn new() -> Arc<Self> { /// fn new() -> Arc<Self> {
/// // `me` is a `Weak<Gadget>` pointing at the new allocation of the /// // `me` is a `Weak<Gadget>` pointing at the new allocation of the
/// // `Arc` we're constructing. /// // `Arc` we're constructing.
@ -438,7 +438,7 @@ impl<T> Arc<T> {
/// }) /// })
/// } /// }
/// ///
/// /// Return a reference counted pointer to Self. /// /// Returns a reference counted pointer to Self.
/// fn me(&self) -> Arc<Self> { /// fn me(&self) -> Arc<Self> {
/// self.me.upgrade().unwrap() /// self.me.upgrade().unwrap()
/// } /// }
@ -2531,7 +2531,7 @@ unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Arc<T, A> {
} }
impl<A: Allocator> Arc<dyn Any + Send + Sync, A> { impl<A: Allocator> Arc<dyn Any + Send + Sync, A> {
/// Attempt to downcast the `Arc<dyn Any + Send + Sync>` to a concrete type. /// Attempts to downcast the `Arc<dyn Any + Send + Sync>` to a concrete type.
/// ///
/// # Examples /// # Examples
/// ///
@ -3545,7 +3545,7 @@ impl<T, const N: usize> From<[T; N]> for Arc<[T]> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T: Clone> From<&[T]> for Arc<[T]> { impl<T: Clone> From<&[T]> for Arc<[T]> {
/// Allocate a reference-counted slice and fill it by cloning `v`'s items. /// Allocates a reference-counted slice and fills it by cloning `v`'s items.
/// ///
/// # Example /// # Example
/// ///
@ -3564,7 +3564,7 @@ impl<T: Clone> From<&[T]> for Arc<[T]> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl From<&str> for Arc<str> { impl From<&str> for Arc<str> {
/// Allocate a reference-counted `str` and copy `v` into it. /// Allocates a reference-counted `str` and copies `v` into it.
/// ///
/// # Example /// # Example
/// ///
@ -3583,7 +3583,7 @@ impl From<&str> for Arc<str> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl From<String> for Arc<str> { impl From<String> for Arc<str> {
/// Allocate a reference-counted `str` and copy `v` into it. /// Allocates a reference-counted `str` and copies `v` into it.
/// ///
/// # Example /// # Example
/// ///
@ -3621,7 +3621,7 @@ impl<T: ?Sized, A: Allocator> From<Box<T, A>> for Arc<T, A> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")] #[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T, A: Allocator + Clone> From<Vec<T, A>> for Arc<[T], A> { impl<T, A: Allocator + Clone> From<Vec<T, A>> for Arc<[T], A> {
/// Allocate a reference-counted slice and move `v`'s items into it. /// Allocates a reference-counted slice and moves `v`'s items into it.
/// ///
/// # Example /// # Example
/// ///
@ -3654,8 +3654,8 @@ where
B: ToOwned + ?Sized, B: ToOwned + ?Sized,
Arc<B>: From<&'a B> + From<B::Owned>, Arc<B>: From<&'a B> + From<B::Owned>,
{ {
/// Create an atomically reference-counted pointer from /// Creates an atomically reference-counted pointer from a clone-on-write
/// a clone-on-write pointer by copying its content. /// pointer by copying its content.
/// ///
/// # Example /// # Example
/// ///
@ -3811,7 +3811,7 @@ impl<T: ?Sized, A: Allocator> AsRef<T> for Arc<T, A> {
#[stable(feature = "pin", since = "1.33.0")] #[stable(feature = "pin", since = "1.33.0")]
impl<T: ?Sized, A: Allocator> Unpin for Arc<T, A> {} impl<T: ?Sized, A: Allocator> Unpin for Arc<T, A> {}
/// Get the offset within an `ArcInner` for the payload behind a pointer. /// Gets the offset within an `ArcInner` for the payload behind a pointer.
/// ///
/// # Safety /// # Safety
/// ///
@ -3833,7 +3833,7 @@ fn data_offset_align(align: usize) -> usize {
layout.size() + layout.padding_needed_for(align) layout.size() + layout.padding_needed_for(align)
} }
/// A unique owning pointer to a [`ArcInner`] **that does not imply the contents are initialized,** /// A unique owning pointer to an [`ArcInner`] **that does not imply the contents are initialized,**
/// but will deallocate it (without dropping the value) when dropped. /// but will deallocate it (without dropping the value) when dropped.
/// ///
/// This is a helper for [`Arc::make_mut()`] to ensure correct cleanup on panic. /// This is a helper for [`Arc::make_mut()`] to ensure correct cleanup on panic.
@ -3846,7 +3846,7 @@ struct UniqueArcUninit<T: ?Sized, A: Allocator> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
impl<T: ?Sized, A: Allocator> UniqueArcUninit<T, A> { impl<T: ?Sized, A: Allocator> UniqueArcUninit<T, A> {
/// Allocate a ArcInner with layout suitable to contain `for_value` or a clone of it. /// Allocates an ArcInner with layout suitable to contain `for_value` or a clone of it.
fn new(for_value: &T, alloc: A) -> UniqueArcUninit<T, A> { fn new(for_value: &T, alloc: A) -> UniqueArcUninit<T, A> {
let layout = Layout::for_value(for_value); let layout = Layout::for_value(for_value);
let ptr = unsafe { let ptr = unsafe {

5
library/alloc/src/vec/into_iter.rs
View File

@ -114,8 +114,9 @@ impl<T, A: Allocator> IntoIter<T, A> {
} }
/// Drops remaining elements and relinquishes the backing allocation. /// Drops remaining elements and relinquishes the backing allocation.
/// This method guarantees it won't panic before relinquishing ///
/// the backing allocation. /// This method guarantees it won't panic before relinquishing the backing
/// allocation.
/// ///
/// This is roughly equivalent to the following, but more efficient /// This is roughly equivalent to the following, but more efficient
/// ///

26
library/alloc/src/vec/mod.rs
View File

@ -2373,9 +2373,11 @@ impl<T, A: Allocator> Vec<T, A> {
} }
/// Consumes and leaks the `Vec`, returning a mutable reference to the contents, /// Consumes and leaks the `Vec`, returning a mutable reference to the contents,
/// `&'a mut [T]`. Note that the type `T` must outlive the chosen lifetime /// `&'a mut [T]`.
/// `'a`. If the type has only static references, or none at all, then this ///
/// may be chosen to be `'static`. /// Note that the type `T` must outlive the chosen lifetime `'a`. If the type
/// has only static references, or none at all, then this may be chosen to be
/// `'static`.
/// ///
/// As of Rust 1.57, this method does not reallocate or shrink the `Vec`, /// As of Rust 1.57, this method does not reallocate or shrink the `Vec`,
/// so the leaked allocation may include unused capacity that is not part /// so the leaked allocation may include unused capacity that is not part
@ -3359,7 +3361,7 @@ impl<T, A: Allocator> AsMut<[T]> for Vec<T, A> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
impl<T: Clone> From<&[T]> for Vec<T> { impl<T: Clone> From<&[T]> for Vec<T> {
/// Allocate a `Vec<T>` and fill it by cloning `s`'s items. /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
/// ///
/// # Examples /// # Examples
/// ///
@ -3379,7 +3381,7 @@ impl<T: Clone> From<&[T]> for Vec<T> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_from_mut", since = "1.19.0")] #[stable(feature = "vec_from_mut", since = "1.19.0")]
impl<T: Clone> From<&mut [T]> for Vec<T> { impl<T: Clone> From<&mut [T]> for Vec<T> {
/// Allocate a `Vec<T>` and fill it by cloning `s`'s items. /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
/// ///
/// # Examples /// # Examples
/// ///
@ -3399,7 +3401,7 @@ impl<T: Clone> From<&mut [T]> for Vec<T> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_from_array_ref", since = "1.74.0")] #[stable(feature = "vec_from_array_ref", since = "1.74.0")]
impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T> { impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T> {
/// Allocate a `Vec<T>` and fill it by cloning `s`'s items. /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
/// ///
/// # Examples /// # Examples
/// ///
@ -3414,7 +3416,7 @@ impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_from_array_ref", since = "1.74.0")] #[stable(feature = "vec_from_array_ref", since = "1.74.0")]
impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T> { impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T> {
/// Allocate a `Vec<T>` and fill it by cloning `s`'s items. /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
/// ///
/// # Examples /// # Examples
/// ///
@ -3429,7 +3431,7 @@ impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_from_array", since = "1.44.0")] #[stable(feature = "vec_from_array", since = "1.44.0")]
impl<T, const N: usize> From<[T; N]> for Vec<T> { impl<T, const N: usize> From<[T; N]> for Vec<T> {
/// Allocate a `Vec<T>` and move `s`'s items into it. /// Allocates a `Vec<T>` and moves `s`'s items into it.
/// ///
/// # Examples /// # Examples
/// ///
@ -3452,7 +3454,7 @@ impl<'a, T> From<Cow<'a, [T]>> for Vec<T>
where where
[T]: ToOwned<Owned = Vec<T>>, [T]: ToOwned<Owned = Vec<T>>,
{ {
/// Convert a clone-on-write slice into a vector. /// Converts a clone-on-write slice into a vector.
/// ///
/// If `s` already owns a `Vec<T>`, it will be returned directly. /// If `s` already owns a `Vec<T>`, it will be returned directly.
/// If `s` is borrowing a slice, a new `Vec<T>` will be allocated and /// If `s` is borrowing a slice, a new `Vec<T>` will be allocated and
@ -3475,7 +3477,7 @@ where
#[cfg(not(test))] #[cfg(not(test))]
#[stable(feature = "vec_from_box", since = "1.18.0")] #[stable(feature = "vec_from_box", since = "1.18.0")]
impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> { impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
/// Convert a boxed slice into a vector by transferring ownership of /// Converts a boxed slice into a vector by transferring ownership of
/// the existing heap allocation. /// the existing heap allocation.
/// ///
/// # Examples /// # Examples
@ -3494,7 +3496,7 @@ impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
#[cfg(not(test))] #[cfg(not(test))]
#[stable(feature = "box_from_vec", since = "1.20.0")] #[stable(feature = "box_from_vec", since = "1.20.0")]
impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> { impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
/// Convert a vector into a boxed slice. /// Converts a vector into a boxed slice.
/// ///
/// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`]. /// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`].
/// ///
@ -3522,7 +3524,7 @@ impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
#[cfg(not(no_global_oom_handling))] #[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
impl From<&str> for Vec<u8> { impl From<&str> for Vec<u8> {
/// Allocate a `Vec<u8>` and fill it with a UTF-8 string. /// Allocates a `Vec<u8>` and fills it with a UTF-8 string.
/// ///
/// # Examples /// # Examples
/// ///

8
library/core/src/alloc/global.rs
View File

@ -118,7 +118,7 @@ use crate::ptr;
/// having side effects. /// having side effects.
#[stable(feature = "global_alloc", since = "1.28.0")] #[stable(feature = "global_alloc", since = "1.28.0")]
pub unsafe trait GlobalAlloc { pub unsafe trait GlobalAlloc {
/// Allocate memory as described by the given `layout`. /// Allocates memory as described by the given `layout`.
/// ///
/// Returns a pointer to newly-allocated memory, /// Returns a pointer to newly-allocated memory,
/// or null to indicate allocation failure. /// or null to indicate allocation failure.
@ -153,7 +153,7 @@ pub unsafe trait GlobalAlloc {
#[stable(feature = "global_alloc", since = "1.28.0")] #[stable(feature = "global_alloc", since = "1.28.0")]
unsafe fn alloc(&self, layout: Layout) -> *mut u8; unsafe fn alloc(&self, layout: Layout) -> *mut u8;
/// Deallocate the block of memory at the given `ptr` pointer with the given `layout`. /// Deallocates the block of memory at the given `ptr` pointer with the given `layout`.
/// ///
/// # Safety /// # Safety
/// ///
@ -200,7 +200,7 @@ pub unsafe trait GlobalAlloc {
ptr ptr
} }
/// Shrink or grow a block of memory to the given `new_size` in bytes. /// Shrinks or grows a block of memory to the given `new_size` in bytes.
/// The block is described by the given `ptr` pointer and `layout`. /// The block is described by the given `ptr` pointer and `layout`.
/// ///
/// If this returns a non-null pointer, then ownership of the memory block /// If this returns a non-null pointer, then ownership of the memory block
@ -232,7 +232,7 @@ pub unsafe trait GlobalAlloc {
/// * `new_size` must be greater than zero. /// * `new_size` must be greater than zero.
/// ///
/// * `new_size`, when rounded up to the nearest multiple of `layout.align()`, /// * `new_size`, when rounded up to the nearest multiple of `layout.align()`,
/// must not overflow isize (i.e., the rounded value must be less than or /// must not overflow `isize` (i.e., the rounded value must be less than or
/// equal to `isize::MAX`). /// equal to `isize::MAX`).
/// ///
/// (Extension subtraits might provide more specific bounds on /// (Extension subtraits might provide more specific bounds on

4
library/core/src/alloc/layout.rs
View File

@ -26,7 +26,7 @@ const fn size_align<T>() -> (usize, usize) {
/// You build a `Layout` up as an input to give to an allocator. /// You build a `Layout` up as an input to give to an allocator.
/// ///
/// All layouts have an associated size and a power-of-two alignment. The size, when rounded up to /// All layouts have an associated size and a power-of-two alignment. The size, when rounded up to
/// the nearest multiple of `align`, does not overflow isize (i.e., the rounded value will always be /// the nearest multiple of `align`, does not overflow `isize` (i.e., the rounded value will always be
/// less than or equal to `isize::MAX`). /// less than or equal to `isize::MAX`).
/// ///
/// (Note that layouts are *not* required to have non-zero size, /// (Note that layouts are *not* required to have non-zero size,
@ -61,7 +61,7 @@ impl Layout {
/// * `align` must be a power of two, /// * `align` must be a power of two,
/// ///
/// * `size`, when rounded up to the nearest multiple of `align`, /// * `size`, when rounded up to the nearest multiple of `align`,
/// must not overflow isize (i.e., the rounded value must be /// must not overflow `isize` (i.e., the rounded value must be
/// less than or equal to `isize::MAX`). /// less than or equal to `isize::MAX`).
#[stable(feature = "alloc_layout", since = "1.28.0")] #[stable(feature = "alloc_layout", since = "1.28.0")]
#[rustc_const_stable(feature = "const_alloc_layout_size_align", since = "1.50.0")] #[rustc_const_stable(feature = "const_alloc_layout_size_align", since = "1.50.0")]

4
library/core/src/array/ascii.rs
View File

@ -2,7 +2,7 @@ use crate::ascii;
#[cfg(not(test))] #[cfg(not(test))]
impl<const N: usize> [u8; N] { impl<const N: usize> [u8; N] {
/// Converts this array of bytes into a array of ASCII characters, /// Converts this array of bytes into an array of ASCII characters,
/// or returns `None` if any of the characters is non-ASCII. /// or returns `None` if any of the characters is non-ASCII.
/// ///
/// # Examples /// # Examples
@ -29,7 +29,7 @@ impl<const N: usize> [u8; N] {
} }
} }
/// Converts this array of bytes into a array of ASCII characters, /// Converts this array of bytes into an array of ASCII characters,
/// without checking whether they're valid. /// without checking whether they're valid.
/// ///
/// # Safety /// # Safety

6
library/core/src/array/iter.rs
View File

@ -47,8 +47,10 @@ impl<T, const N: usize> IntoIterator for [T; N] {
type IntoIter = IntoIter<T, N>; type IntoIter = IntoIter<T, N>;
/// Creates a consuming iterator, that is, one that moves each value out of /// Creates a consuming iterator, that is, one that moves each value out of
/// the array (from start to end). The array cannot be used after calling /// the array (from start to end).
/// this unless `T` implements `Copy`, so the whole array is copied. ///
/// The array cannot be used after calling this unless `T` implements
/// `Copy`, so the whole array is copied.
/// ///
/// Arrays have special behavior when calling `.into_iter()` prior to the /// Arrays have special behavior when calling `.into_iter()` prior to the
/// 2021 edition -- see the [array] Editions section for more information. /// 2021 edition -- see the [array] Editions section for more information.

4
library/core/src/async_iter/async_iter.rs
View File

@ -18,7 +18,7 @@ pub trait AsyncIterator {
/// The type of items yielded by the async iterator. /// The type of items yielded by the async iterator.
type Item; type Item;
/// Attempt to pull out the next value of this async iterator, registering the /// Attempts to pull out the next value of this async iterator, registering the
/// current task for wakeup if the value is not yet available, and returning /// current task for wakeup if the value is not yet available, and returning
/// `None` if the async iterator is exhausted. /// `None` if the async iterator is exhausted.
/// ///
@ -139,7 +139,7 @@ impl<T> Poll<Option<T>> {
pub const FINISHED: Self = Poll::Ready(None); pub const FINISHED: Self = Poll::Ready(None);
} }
/// Convert something into an async iterator /// Converts something into an async iterator
#[unstable(feature = "async_iterator", issue = "79024")] #[unstable(feature = "async_iterator", issue = "79024")]
pub trait IntoAsyncIterator { pub trait IntoAsyncIterator {
/// The type of the item yielded by the iterator /// The type of the item yielded by the iterator

12
library/core/src/cell.rs
View File

@ -427,7 +427,9 @@ impl<T> Cell<T> {
} }
/// Swaps the values of two `Cell`s. /// Swaps the values of two `Cell`s.
/// Difference with `std::mem::swap` is that this function doesn't require `&mut` reference. ///
/// The difference with `std::mem::swap` is that this function doesn't
/// require a `&mut` reference.
/// ///
/// # Panics /// # Panics
/// ///
@ -1579,7 +1581,7 @@ impl<'b, T: ?Sized> Ref<'b, T> {
) )
} }
/// Convert into a reference to the underlying data. /// Converts into a reference to the underlying data.
/// ///
/// The underlying `RefCell` can never be mutably borrowed from again and will always appear /// The underlying `RefCell` can never be mutably borrowed from again and will always appear
/// already immutably borrowed. It is not a good idea to leak more than a constant number of /// already immutably borrowed. It is not a good idea to leak more than a constant number of
@ -1747,7 +1749,7 @@ impl<'b, T: ?Sized> RefMut<'b, T> {
) )
} }
/// Convert into a mutable reference to the underlying data. /// Converts into a mutable reference to the underlying data.
/// ///
/// The underlying `RefCell` can not be borrowed from again and will always appear already /// The underlying `RefCell` can not be borrowed from again and will always appear already
/// mutably borrowed, making the returned reference the only to the interior. /// mutably borrowed, making the returned reference the only to the interior.
@ -1879,7 +1881,7 @@ impl<T: ?Sized + fmt::Display> fmt::Display for RefMut<'_, T> {
/// ///
/// If you have a reference `&T`, then normally in Rust the compiler performs optimizations based on /// If you have a reference `&T`, then normally in Rust the compiler performs optimizations based on
/// the knowledge that `&T` points to immutable data. Mutating that data, for example through an /// the knowledge that `&T` points to immutable data. Mutating that data, for example through an
/// alias or by transmuting an `&T` into an `&mut T`, is considered undefined behavior. /// alias or by transmuting a `&T` into a `&mut T`, is considered undefined behavior.
/// `UnsafeCell<T>` opts-out of the immutability guarantee for `&T`: a shared reference /// `UnsafeCell<T>` opts-out of the immutability guarantee for `&T`: a shared reference
/// `&UnsafeCell<T>` may point to data that is being mutated. This is called "interior mutability". /// `&UnsafeCell<T>` may point to data that is being mutated. This is called "interior mutability".
/// ///
@ -1936,7 +1938,7 @@ impl<T: ?Sized + fmt::Display> fmt::Display for RefMut<'_, T> {
/// to have multiple `&mut UnsafeCell<T>` aliases. That is, `UnsafeCell` is a wrapper /// to have multiple `&mut UnsafeCell<T>` aliases. That is, `UnsafeCell` is a wrapper
/// designed to have a special interaction with _shared_ accesses (_i.e._, through an /// designed to have a special interaction with _shared_ accesses (_i.e._, through an
/// `&UnsafeCell<_>` reference); there is no magic whatsoever when dealing with _exclusive_ /// `&UnsafeCell<_>` reference); there is no magic whatsoever when dealing with _exclusive_
/// accesses (_e.g._, through an `&mut UnsafeCell<_>`): neither the cell nor the wrapped value /// accesses (_e.g._, through a `&mut UnsafeCell<_>`): neither the cell nor the wrapped value
/// may be aliased for the duration of that `&mut` borrow. /// may be aliased for the duration of that `&mut` borrow.
/// This is showcased by the [`.get_mut()`] accessor, which is a _safe_ getter that yields /// This is showcased by the [`.get_mut()`] accessor, which is a _safe_ getter that yields
/// a `&mut T`. /// a `&mut T`.

20
library/core/src/cmp.rs
View File

@ -246,15 +246,14 @@ use self::Ordering::*;
)] )]
#[rustc_diagnostic_item = "PartialEq"] #[rustc_diagnostic_item = "PartialEq"]
pub trait PartialEq<Rhs: ?Sized = Self> { pub trait PartialEq<Rhs: ?Sized = Self> {
/// This method tests for `self` and `other` values to be equal, and is used /// Tests for `self` and `other` values to be equal, and is used by `==`.
/// by `==`.
#[must_use] #[must_use]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[rustc_diagnostic_item = "cmp_partialeq_eq"] #[rustc_diagnostic_item = "cmp_partialeq_eq"]
fn eq(&self, other: &Rhs) -> bool; fn eq(&self, other: &Rhs) -> bool;
/// This method tests for `!=`. The default implementation is almost always /// Tests for `!=`. The default implementation is almost always sufficient,
/// sufficient, and should not be overridden without very good reason. /// and should not be overridden without very good reason.
#[inline] #[inline]
#[must_use] #[must_use]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
@ -1163,7 +1162,7 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
#[rustc_diagnostic_item = "cmp_partialord_cmp"] #[rustc_diagnostic_item = "cmp_partialord_cmp"]
fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>; fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>;
/// This method tests less than (for `self` and `other`) and is used by the `<` operator. /// Tests less than (for `self` and `other`) and is used by the `<` operator.
/// ///
/// # Examples /// # Examples
/// ///
@ -1180,8 +1179,8 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
matches!(self.partial_cmp(other), Some(Less)) matches!(self.partial_cmp(other), Some(Less))
} }
/// This method tests less than or equal to (for `self` and `other`) and is used by the `<=` /// Tests less than or equal to (for `self` and `other`) and is used by the
/// operator. /// `<=` operator.
/// ///
/// # Examples /// # Examples
/// ///
@ -1198,7 +1197,8 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
matches!(self.partial_cmp(other), Some(Less | Equal)) matches!(self.partial_cmp(other), Some(Less | Equal))
} }
/// This method tests greater than (for `self` and `other`) and is used by the `>` operator. /// Tests greater than (for `self` and `other`) and is used by the `>`
/// operator.
/// ///
/// # Examples /// # Examples
/// ///
@ -1215,8 +1215,8 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
matches!(self.partial_cmp(other), Some(Greater)) matches!(self.partial_cmp(other), Some(Greater))
} }
/// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` /// Tests greater than or equal to (for `self` and `other`) and is used by
/// operator. /// the `>=` operator.
/// ///
/// # Examples /// # Examples
/// ///

8
library/core/src/convert/num.rs
View File

@ -208,7 +208,7 @@ macro_rules! impl_try_from_unbounded {
impl TryFrom<$source> for $target { impl TryFrom<$source> for $target {
type Error = TryFromIntError; type Error = TryFromIntError;
/// Try to create the target number type from a source /// Tries to create the target number type from a source
/// number type. This returns an error if the source value /// number type. This returns an error if the source value
/// is outside of the range of the target type. /// is outside of the range of the target type.
#[inline] #[inline]
@ -226,7 +226,7 @@ macro_rules! impl_try_from_lower_bounded {
impl TryFrom<$source> for $target { impl TryFrom<$source> for $target {
type Error = TryFromIntError; type Error = TryFromIntError;
/// Try to create the target number type from a source /// Tries to create the target number type from a source
/// number type. This returns an error if the source value /// number type. This returns an error if the source value
/// is outside of the range of the target type. /// is outside of the range of the target type.
#[inline] #[inline]
@ -248,7 +248,7 @@ macro_rules! impl_try_from_upper_bounded {
impl TryFrom<$source> for $target { impl TryFrom<$source> for $target {
type Error = TryFromIntError; type Error = TryFromIntError;
/// Try to create the target number type from a source /// Tries to create the target number type from a source
/// number type. This returns an error if the source value /// number type. This returns an error if the source value
/// is outside of the range of the target type. /// is outside of the range of the target type.
#[inline] #[inline]
@ -270,7 +270,7 @@ macro_rules! impl_try_from_both_bounded {
impl TryFrom<$source> for $target { impl TryFrom<$source> for $target {
type Error = TryFromIntError; type Error = TryFromIntError;
/// Try to create the target number type from a source /// Tries to create the target number type from a source
/// number type. This returns an error if the source value /// number type. This returns an error if the source value
/// is outside of the range of the target type. /// is outside of the range of the target type.
#[inline] #[inline]

33
library/core/src/error.rs
View File

@ -30,7 +30,7 @@ use crate::fmt::{Debug, Display, Formatter, Result};
#[rustc_has_incoherent_inherent_impls] #[rustc_has_incoherent_inherent_impls]
#[allow(multiple_supertrait_upcastable)] #[allow(multiple_supertrait_upcastable)]
pub trait Error: Debug + Display { pub trait Error: Debug + Display {
/// The lower-level source of this error, if any. /// Returns the lower-level source of this error, if any.
/// ///
/// # Examples /// # Examples
/// ///
@ -121,7 +121,7 @@ pub trait Error: Debug + Display {
self.source() self.source()
} }
/// Provides type based access to context intended for error reports. /// Provides type-based access to context intended for error reports.
/// ///
/// Used in conjunction with [`Request::provide_value`] and [`Request::provide_ref`] to extract /// Used in conjunction with [`Request::provide_value`] and [`Request::provide_ref`] to extract
/// references to member variables from `dyn Error` trait objects. /// references to member variables from `dyn Error` trait objects.
@ -353,7 +353,7 @@ impl dyn Error {
} }
} }
/// Request a value of type `T` from the given `impl Error`. /// Requests a value of type `T` from the given `impl Error`.
/// ///
/// # Examples /// # Examples
/// ///
@ -376,7 +376,7 @@ where
request_by_type_tag::<'a, tags::Value<T>>(err) request_by_type_tag::<'a, tags::Value<T>>(err)
} }
/// Request a reference of type `T` from the given `impl Error`. /// Requests a reference of type `T` from the given `impl Error`.
/// ///
/// # Examples /// # Examples
/// ///
@ -510,7 +510,7 @@ where
pub struct Request<'a>(Tagged<dyn Erased<'a> + 'a>); pub struct Request<'a>(Tagged<dyn Erased<'a> + 'a>);
impl<'a> Request<'a> { impl<'a> Request<'a> {
/// Provide a value or other type with only static lifetimes. /// Provides a value or other type with only static lifetimes.
/// ///
/// # Examples /// # Examples
/// ///
@ -544,7 +544,7 @@ impl<'a> Request<'a> {
self.provide::<tags::Value<T>>(value) self.provide::<tags::Value<T>>(value)
} }
/// Provide a value or other type with only static lifetimes computed using a closure. /// Provides a value or other type with only static lifetimes computed using a closure.
/// ///
/// # Examples /// # Examples
/// ///
@ -578,7 +578,7 @@ impl<'a> Request<'a> {
self.provide_with::<tags::Value<T>>(fulfil) self.provide_with::<tags::Value<T>>(fulfil)
} }
/// Provide a reference. The referee type must be bounded by `'static`, /// Provides a reference. The referee type must be bounded by `'static`,
/// but may be unsized. /// but may be unsized.
/// ///
/// # Examples /// # Examples
@ -610,7 +610,7 @@ impl<'a> Request<'a> {
self.provide::<tags::Ref<tags::MaybeSizedValue<T>>>(value) self.provide::<tags::Ref<tags::MaybeSizedValue<T>>>(value)
} }
/// Provide a reference computed using a closure. The referee type /// Provides a reference computed using a closure. The referee type
/// must be bounded by `'static`, but may be unsized. /// must be bounded by `'static`, but may be unsized.
/// ///
/// # Examples /// # Examples
@ -652,7 +652,7 @@ impl<'a> Request<'a> {
self.provide_with::<tags::Ref<tags::MaybeSizedValue<T>>>(fulfil) self.provide_with::<tags::Ref<tags::MaybeSizedValue<T>>>(fulfil)
} }
/// Provide a value with the given `Type` tag. /// Provides a value with the given `Type` tag.
fn provide<I>(&mut self, value: I::Reified) -> &mut Self fn provide<I>(&mut self, value: I::Reified) -> &mut Self
where where
I: tags::Type<'a>, I: tags::Type<'a>,
@ -663,7 +663,7 @@ impl<'a> Request<'a> {
self self
} }
/// Provide a value with the given `Type` tag, using a closure to prevent unnecessary work. /// Provides a value with the given `Type` tag, using a closure to prevent unnecessary work.
fn provide_with<I>(&mut self, fulfil: impl FnOnce() -> I::Reified) -> &mut Self fn provide_with<I>(&mut self, fulfil: impl FnOnce() -> I::Reified) -> &mut Self
where where
I: tags::Type<'a>, I: tags::Type<'a>,
@ -674,13 +674,13 @@ impl<'a> Request<'a> {
self self
} }
/// Check if the `Request` would be satisfied if provided with a /// Checks if the `Request` would be satisfied if provided with a
/// value of the specified type. If the type does not match or has /// value of the specified type. If the type does not match or has
/// already been provided, returns false. /// already been provided, returns false.
/// ///
/// # Examples /// # Examples
/// ///
/// Check if an `u8` still needs to be provided and then provides /// Checks if a `u8` still needs to be provided and then provides
/// it. /// it.
/// ///
/// ```rust /// ```rust
@ -761,13 +761,14 @@ impl<'a> Request<'a> {
self.would_be_satisfied_by::<tags::Value<T>>() self.would_be_satisfied_by::<tags::Value<T>>()
} }
/// Check if the `Request` would be satisfied if provided with a /// Checks if the `Request` would be satisfied if provided with a
/// reference to a value of the specified type. If the type does /// reference to a value of the specified type.
/// not match or has already been provided, returns false. ///
/// If the type does not match or has already been provided, returns false.
/// ///
/// # Examples /// # Examples
/// ///
/// Check if a `&str` still needs to be provided and then provides /// Checks if a `&str` still needs to be provided and then provides
/// it. /// it.
/// ///
/// ```rust /// ```rust

4
library/core/src/ffi/va_list.rs
View File

@ -162,7 +162,7 @@ pub struct VaList<'a, 'f: 'a> {
windows, windows,
))] ))]
impl<'f> VaListImpl<'f> { impl<'f> VaListImpl<'f> {
/// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`. /// Converts a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
#[inline] #[inline]
pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> { pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
VaList { inner: VaListImpl { ..*self }, _marker: PhantomData } VaList { inner: VaListImpl { ..*self }, _marker: PhantomData }
@ -182,7 +182,7 @@ impl<'f> VaListImpl<'f> {
not(windows), not(windows),
))] ))]
impl<'f> VaListImpl<'f> { impl<'f> VaListImpl<'f> {
/// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`. /// Converts a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`.
#[inline] #[inline]
pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> { pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> {
VaList { inner: self, _marker: PhantomData } VaList { inner: self, _marker: PhantomData }

98
library/core/src/fmt/mod.rs
View File

@ -354,7 +354,7 @@ impl<'a> Arguments<'a> {
Arguments { pieces, fmt: None, args } Arguments { pieces, fmt: None, args }
} }
/// This function is used to specify nonstandard formatting parameters. /// Specifies nonstandard formatting parameters.
/// ///
/// An `rt::UnsafeArg` is required because the following invariants must be held /// An `rt::UnsafeArg` is required because the following invariants must be held
/// in order for this function to be safe: /// in order for this function to be safe:
@ -396,7 +396,7 @@ impl<'a> Arguments<'a> {
} }
impl<'a> Arguments<'a> { impl<'a> Arguments<'a> {
/// Get the formatted string, if it has no arguments to be formatted at runtime. /// Gets the formatted string, if it has no arguments to be formatted at runtime.
/// ///
/// This can be used to avoid allocations in some cases. /// This can be used to avoid allocations in some cases.
/// ///
@ -1129,8 +1129,8 @@ pub trait UpperExp {
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
/// The `write` function takes an output stream, and an `Arguments` struct /// Takes an output stream and an `Arguments` struct that can be precompiled with
/// that can be precompiled with the `format_args!` macro. /// the `format_args!` macro.
/// ///
/// The arguments will be formatted according to the specified format string /// The arguments will be formatted according to the specified format string
/// into the output stream provided. /// into the output stream provided.
@ -1257,7 +1257,7 @@ impl PostPadding {
PostPadding { fill, padding } PostPadding { fill, padding }
} }
/// Write this post padding. /// Writes this post padding.
pub(crate) fn write(self, f: &mut Formatter<'_>) -> Result { pub(crate) fn write(self, f: &mut Formatter<'_>) -> Result {
for _ in 0..self.padding { for _ in 0..self.padding {
f.buf.write_char(self.fill)?; f.buf.write_char(self.fill)?;
@ -1398,9 +1398,10 @@ impl<'a> Formatter<'a> {
} }
} }
/// This function takes a string slice and emits it to the internal buffer /// Takes a string slice and emits it to the internal buffer after applying
/// after applying the relevant formatting flags specified. The flags /// the relevant formatting flags specified.
/// recognized for generic strings are: ///
/// The flags recognized for generic strings are:
/// ///
/// * width - the minimum width of what to emit /// * width - the minimum width of what to emit
/// * fill/align - what to emit and where to emit it if the string /// * fill/align - what to emit and where to emit it if the string
@ -1474,9 +1475,10 @@ impl<'a> Formatter<'a> {
} }
} }
/// Write the pre-padding and return the unwritten post-padding. Callers are /// Writes the pre-padding and returns the unwritten post-padding.
/// responsible for ensuring post-padding is written after the thing that is ///
/// being padded. /// Callers are responsible for ensuring post-padding is written after the
/// thing that is being padded.
pub(crate) fn padding( pub(crate) fn padding(
&mut self, &mut self,
padding: usize, padding: usize,
@ -1503,6 +1505,7 @@ impl<'a> Formatter<'a> {
} }
/// Takes the formatted parts and applies the padding. /// Takes the formatted parts and applies the padding.
///
/// Assumes that the caller already has rendered the parts with required precision, /// Assumes that the caller already has rendered the parts with required precision,
/// so that `self.precision` can be ignored. /// so that `self.precision` can be ignored.
/// ///
@ -1655,7 +1658,7 @@ impl<'a> Formatter<'a> {
} }
} }
/// Flags for formatting /// Returns flags for formatting.
#[must_use] #[must_use]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[deprecated( #[deprecated(
@ -1667,7 +1670,7 @@ impl<'a> Formatter<'a> {
self.flags self.flags
} }
/// Character used as 'fill' whenever there is alignment. /// Returns the character used as 'fill' whenever there is alignment.
/// ///
/// # Examples /// # Examples
/// ///
@ -1700,7 +1703,7 @@ impl<'a> Formatter<'a> {
self.fill self.fill
} }
/// Flag indicating what form of alignment was requested. /// Returns a flag indicating what form of alignment was requested.
/// ///
/// # Examples /// # Examples
/// ///
@ -1740,7 +1743,7 @@ impl<'a> Formatter<'a> {
} }
} }
/// Optionally specified integer width that the output should be. /// Returns the optionally specified integer width that the output should be.
/// ///
/// # Examples /// # Examples
/// ///
@ -1770,8 +1773,8 @@ impl<'a> Formatter<'a> {
self.width self.width
} }
/// Optionally specified precision for numeric types. Alternatively, the /// Returns the optionally specified precision for numeric types.
/// maximum width for string types. /// Alternatively, the maximum width for string types.
/// ///
/// # Examples /// # Examples
/// ///
@ -1967,8 +1970,9 @@ impl<'a> Formatter<'a> {
builders::debug_struct_new(self, name) builders::debug_struct_new(self, name)
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_struct_fields_finish` is more general, but this is faster for 1 field. /// binaries. `debug_struct_fields_finish` is more general, but this is
/// faster for 1 field.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_struct_field1_finish<'b>( pub fn debug_struct_field1_finish<'b>(
@ -1982,8 +1986,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_struct_fields_finish` is more general, but this is faster for 2 fields. /// binaries. `debug_struct_fields_finish` is more general, but this is
/// faster for 2 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_struct_field2_finish<'b>( pub fn debug_struct_field2_finish<'b>(
@ -2000,8 +2005,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_struct_fields_finish` is more general, but this is faster for 3 fields. /// binaries. `debug_struct_fields_finish` is more general, but this is
/// faster for 3 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_struct_field3_finish<'b>( pub fn debug_struct_field3_finish<'b>(
@ -2021,8 +2027,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_struct_fields_finish` is more general, but this is faster for 4 fields. /// binaries. `debug_struct_fields_finish` is more general, but this is
/// faster for 4 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_struct_field4_finish<'b>( pub fn debug_struct_field4_finish<'b>(
@ -2045,8 +2052,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_struct_fields_finish` is more general, but this is faster for 5 fields. /// binaries. `debug_struct_fields_finish` is more general, but this is
/// faster for 5 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_struct_field5_finish<'b>( pub fn debug_struct_field5_finish<'b>(
@ -2072,7 +2080,7 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller binaries.
/// For the cases not covered by `debug_struct_field[12345]_finish`. /// For the cases not covered by `debug_struct_field[12345]_finish`.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
@ -2121,8 +2129,9 @@ impl<'a> Formatter<'a> {
builders::debug_tuple_new(self, name) builders::debug_tuple_new(self, name)
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_tuple_fields_finish` is more general, but this is faster for 1 field. /// binaries. `debug_tuple_fields_finish` is more general, but this is faster
/// for 1 field.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_tuple_field1_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug) -> Result { pub fn debug_tuple_field1_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug) -> Result {
@ -2131,8 +2140,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_tuple_fields_finish` is more general, but this is faster for 2 fields. /// binaries. `debug_tuple_fields_finish` is more general, but this is faster
/// for 2 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_tuple_field2_finish<'b>( pub fn debug_tuple_field2_finish<'b>(
@ -2147,8 +2157,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_tuple_fields_finish` is more general, but this is faster for 3 fields. /// binaries. `debug_tuple_fields_finish` is more general, but this is faster
/// for 3 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_tuple_field3_finish<'b>( pub fn debug_tuple_field3_finish<'b>(
@ -2165,8 +2176,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_tuple_fields_finish` is more general, but this is faster for 4 fields. /// binaries. `debug_tuple_fields_finish` is more general, but this is faster
/// for 4 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_tuple_field4_finish<'b>( pub fn debug_tuple_field4_finish<'b>(
@ -2185,8 +2197,9 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// `debug_tuple_fields_finish` is more general, but this is faster for 5 fields. /// binaries. `debug_tuple_fields_finish` is more general, but this is faster
/// for 5 fields.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_tuple_field5_finish<'b>( pub fn debug_tuple_field5_finish<'b>(
@ -2207,8 +2220,8 @@ impl<'a> Formatter<'a> {
builder.finish() builder.finish()
} }
/// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. /// Shrinks `derive(Debug)` code, for faster compilation and smaller
/// For the cases not covered by `debug_tuple_field[12345]_finish`. /// binaries. For the cases not covered by `debug_tuple_field[12345]_finish`.
#[doc(hidden)] #[doc(hidden)]
#[unstable(feature = "fmt_helpers_for_derive", issue = "none")] #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
pub fn debug_tuple_fields_finish<'b>( pub fn debug_tuple_fields_finish<'b>(
@ -2496,8 +2509,9 @@ impl<T: ?Sized> Pointer for *const T {
} }
} }
/// Since the formatting will be identical for all pointer types, use a non-monomorphized /// Since the formatting will be identical for all pointer types, uses a
/// implementation for the actual formatting to reduce the amount of codegen work needed. /// non-monomorphized implementation for the actual formatting to reduce the
/// amount of codegen work needed.
/// ///
/// This uses `ptr_addr: usize` and not `ptr: *const ()` to be able to use this for /// This uses `ptr_addr: usize` and not `ptr: *const ()` to be able to use this for
/// `fn(...) -> ...` without using [problematic] "Oxford Casts". /// `fn(...) -> ...` without using [problematic] "Oxford Casts".

6
library/core/src/future/async_drop.rs
View File

@ -205,7 +205,7 @@ async unsafe fn slice<T>(s: *mut [T]) {
} }
} }
/// Construct a chain of two futures, which awaits them sequentially as /// Constructs a chain of two futures, which awaits them sequentially as
/// a future. /// a future.
#[lang = "async_drop_chain"] #[lang = "async_drop_chain"]
async fn chain<F, G>(first: F, last: G) async fn chain<F, G>(first: F, last: G)
@ -235,8 +235,8 @@ async unsafe fn defer<T: ?Sized>(to_drop: *mut T) {
/// ///
/// # Safety /// # Safety
/// ///
/// User should carefully manage returned future, since it would /// Users should carefully manage the returned future, since it would
/// try creating an immutable referece from `this` and get pointee's /// try creating an immutable reference from `this` and get pointee's
/// discriminant. /// discriminant.
// FIXME(zetanumbers): Send and Sync impls // FIXME(zetanumbers): Send and Sync impls
#[lang = "async_drop_either"] #[lang = "async_drop_either"]

2
library/core/src/future/future.rs
View File

@ -38,7 +38,7 @@ pub trait Future {
#[lang = "future_output"] #[lang = "future_output"]
type Output; type Output;
/// Attempt to resolve the future to a final value, registering /// Attempts to resolve the future to a final value, registering
/// the current task for wakeup if the value is not yet available. /// the current task for wakeup if the value is not yet available.
/// ///
/// # Return value /// # Return value

4
library/core/src/future/into_future.rs
View File

@ -40,7 +40,7 @@ use crate::future::Future;
/// } /// }
/// ///
/// impl Multiply { /// impl Multiply {
/// /// Construct a new instance of `Multiply`. /// /// Constructs a new instance of `Multiply`.
/// pub fn new(num: u16, factor: u16) -> Self { /// pub fn new(num: u16, factor: u16) -> Self {
/// Self { num, factor } /// Self { num, factor }
/// } /// }
@ -89,7 +89,7 @@ use crate::future::Future;
/// ```rust /// ```rust
/// use std::future::IntoFuture; /// use std::future::IntoFuture;
/// ///
/// /// Convert the output of a future to a string. /// /// Converts the output of a future to a string.
/// async fn fut_to_string<Fut>(fut: Fut) -> String /// async fn fut_to_string<Fut>(fut: Fut) -> String
/// where /// where
/// Fut: IntoFuture, /// Fut: IntoFuture,

2
library/core/src/internal_macros.rs
View File

@ -80,7 +80,7 @@ macro_rules! forward_ref_op_assign {
} }
} }
/// Create a zero-size type similar to a closure type, but named. /// Creates a zero-size type similar to a closure type, but named.
macro_rules! impl_fn_for_zst { macro_rules! impl_fn_for_zst {
($( ($(
$( #[$attr: meta] )* $( #[$attr: meta] )*

10
library/core/src/intrinsics.rs
View File

@ -1252,7 +1252,7 @@ extern "rust-intrinsic" {
/// - If the code actually wants to work on the address the pointer points to, it can use `as` /// - If the code actually wants to work on the address the pointer points to, it can use `as`
/// casts or [`ptr.addr()`][pointer::addr]. /// casts or [`ptr.addr()`][pointer::addr].
/// ///
/// Turning a `*mut T` into an `&mut T`: /// Turning a `*mut T` into a `&mut T`:
/// ///
/// ``` /// ```
/// let ptr: *mut i32 = &mut 0; /// let ptr: *mut i32 = &mut 0;
@ -1264,7 +1264,7 @@ extern "rust-intrinsic" {
/// let ref_casted = unsafe { &mut *ptr }; /// let ref_casted = unsafe { &mut *ptr };
/// ``` /// ```
/// ///
/// Turning an `&mut T` into an `&mut U`: /// Turning a `&mut T` into a `&mut U`:
/// ///
/// ``` /// ```
/// let ptr = &mut 0; /// let ptr = &mut 0;
@ -1277,7 +1277,7 @@ extern "rust-intrinsic" {
/// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) }; /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
/// ``` /// ```
/// ///
/// Turning an `&str` into a `&[u8]`: /// Turning a `&str` into a `&[u8]`:
/// ///
/// ``` /// ```
/// // this is not a good way to do this. /// // this is not a good way to do this.
@ -1363,7 +1363,7 @@ extern "rust-intrinsic" {
/// } /// }
/// ///
/// // This gets rid of the type safety problems; `&mut *` will *only* give /// // This gets rid of the type safety problems; `&mut *` will *only* give
/// // you an `&mut T` from an `&mut T` or `*mut T`. /// // you a `&mut T` from a `&mut T` or `*mut T`.
/// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize) /// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
/// -> (&mut [T], &mut [T]) { /// -> (&mut [T], &mut [T]) {
/// let len = slice.len(); /// let len = slice.len();
@ -1944,7 +1944,7 @@ extern "rust-intrinsic" {
#[rustc_safe_intrinsic] #[rustc_safe_intrinsic]
pub fn frem_algebraic<T: Copy>(a: T, b: T) -> T; pub fn frem_algebraic<T: Copy>(a: T, b: T) -> T;
/// Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range /// Converts with LLVM’s fptoui/fptosi, which may return undef for values out of range
/// (<https://github.com/rust-lang/rust/issues/10184>) /// (<https://github.com/rust-lang/rust/issues/10184>)
/// ///
/// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`]. /// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`].

109
library/core/src/intrinsics/simd.rs
View File

@ -3,7 +3,7 @@
//! In this module, a "vector" is any `repr(simd)` type. //! In this module, a "vector" is any `repr(simd)` type.
extern "rust-intrinsic" { extern "rust-intrinsic" {
/// Insert an element into a vector, returning the updated vector. /// Inserts an element into a vector, returning the updated vector.
/// ///
/// `T` must be a vector with element type `U`. /// `T` must be a vector with element type `U`.
/// ///
@ -13,7 +13,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_insert<T, U>(x: T, idx: u32, val: U) -> T; pub fn simd_insert<T, U>(x: T, idx: u32, val: U) -> T;
/// Extract an element from a vector. /// Extracts an element from a vector.
/// ///
/// `T` must be a vector with element type `U`. /// `T` must be a vector with element type `U`.
/// ///
@ -23,25 +23,25 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_extract<T, U>(x: T, idx: u32) -> U; pub fn simd_extract<T, U>(x: T, idx: u32) -> U;
/// Add two simd vectors elementwise. /// Adds two simd vectors elementwise.
/// ///
/// `T` must be a vector of integer or floating point primitive types. /// `T` must be a vector of integer or floating point primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_add<T>(x: T, y: T) -> T; pub fn simd_add<T>(x: T, y: T) -> T;
/// Subtract `rhs` from `lhs` elementwise. /// Subtracts `rhs` from `lhs` elementwise.
/// ///
/// `T` must be a vector of integer or floating point primitive types. /// `T` must be a vector of integer or floating point primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_sub<T>(lhs: T, rhs: T) -> T; pub fn simd_sub<T>(lhs: T, rhs: T) -> T;
/// Multiply two simd vectors elementwise. /// Multiplies two simd vectors elementwise.
/// ///
/// `T` must be a vector of integer or floating point primitive types. /// `T` must be a vector of integer or floating point primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_mul<T>(x: T, y: T) -> T; pub fn simd_mul<T>(x: T, y: T) -> T;
/// Divide `lhs` by `rhs` elementwise. /// Divides `lhs` by `rhs` elementwise.
/// ///
/// `T` must be a vector of integer or floating point primitive types. /// `T` must be a vector of integer or floating point primitive types.
/// ///
@ -51,7 +51,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_div<T>(lhs: T, rhs: T) -> T; pub fn simd_div<T>(lhs: T, rhs: T) -> T;
/// Remainder of two vectors elementwise /// Returns remainder of two vectors elementwise.
/// ///
/// `T` must be a vector of integer or floating point primitive types. /// `T` must be a vector of integer or floating point primitive types.
/// ///
@ -61,9 +61,9 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_rem<T>(lhs: T, rhs: T) -> T; pub fn simd_rem<T>(lhs: T, rhs: T) -> T;
/// Elementwise vector left shift, with UB on overflow. /// Shifts vector left elementwise, with UB on overflow.
/// ///
/// Shift `lhs` left by `rhs`, shifting in sign bits for signed types. /// Shifts `lhs` left by `rhs`, shifting in sign bits for signed types.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
/// ///
@ -73,11 +73,11 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_shl<T>(lhs: T, rhs: T) -> T; pub fn simd_shl<T>(lhs: T, rhs: T) -> T;
/// Elementwise vector right shift, with UB on overflow. /// Shifts vector right elementwise, with UB on overflow.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
/// ///
/// Shift `lhs` right by `rhs`, shifting in sign bits for signed types. /// Shifts `lhs` right by `rhs`, shifting in sign bits for signed types.
/// ///
/// # Safety /// # Safety
/// ///
@ -85,25 +85,25 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_shr<T>(lhs: T, rhs: T) -> T; pub fn simd_shr<T>(lhs: T, rhs: T) -> T;
/// Elementwise vector "and". /// "Ands" vectors elementwise.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_and<T>(x: T, y: T) -> T; pub fn simd_and<T>(x: T, y: T) -> T;
/// Elementwise vector "or". /// "Ors" vectors elementwise.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_or<T>(x: T, y: T) -> T; pub fn simd_or<T>(x: T, y: T) -> T;
/// Elementwise vector "exclusive or". /// "Exclusive ors" vectors elementwise.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_xor<T>(x: T, y: T) -> T; pub fn simd_xor<T>(x: T, y: T) -> T;
/// Numerically cast a vector, elementwise. /// Numerically casts a vector, elementwise.
/// ///
/// `T` and `U` must be vectors of integer or floating point primitive types, and must have the /// `T` and `U` must be vectors of integer or floating point primitive types, and must have the
/// same length. /// same length.
@ -124,7 +124,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_cast<T, U>(x: T) -> U; pub fn simd_cast<T, U>(x: T) -> U;
/// Numerically cast a vector, elementwise. /// Numerically casts a vector, elementwise.
/// ///
/// `T` and `U` be a vectors of integer or floating point primitive types, and must have the /// `T` and `U` be a vectors of integer or floating point primitive types, and must have the
/// same length. /// same length.
@ -138,7 +138,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_as<T, U>(x: T) -> U; pub fn simd_as<T, U>(x: T) -> U;
/// Elementwise negation of a vector. /// Negates a vector elementwise.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -146,13 +146,13 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_neg<T>(x: T) -> T; pub fn simd_neg<T>(x: T) -> T;
/// Elementwise absolute value of a vector. /// Returns absolute value of a vector, elementwise.
/// ///
/// `T` must be a vector of floating-point primitive types. /// `T` must be a vector of floating-point primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_fabs<T>(x: T) -> T; pub fn simd_fabs<T>(x: T) -> T;
/// Elementwise minimum of two vectors. /// Returns the minimum of two vectors, elementwise.
/// ///
/// `T` must be a vector of floating-point primitive types. /// `T` must be a vector of floating-point primitive types.
/// ///
@ -160,7 +160,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_fmin<T>(x: T, y: T) -> T; pub fn simd_fmin<T>(x: T, y: T) -> T;
/// Elementwise maximum of two vectors. /// Returns the maximum of two vectors, elementwise.
/// ///
/// `T` must be a vector of floating-point primitive types. /// `T` must be a vector of floating-point primitive types.
/// ///
@ -228,7 +228,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_ge<T, U>(x: T, y: T) -> U; pub fn simd_ge<T, U>(x: T, y: T) -> U;
/// Shuffle two vectors by const indices. /// Shuffles two vectors by const indices.
/// ///
/// `T` must be a vector. /// `T` must be a vector.
/// ///
@ -243,7 +243,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_shuffle<T, U, V>(x: T, y: T, idx: U) -> V; pub fn simd_shuffle<T, U, V>(x: T, y: T, idx: U) -> V;
/// Read a vector of pointers. /// Reads a vector of pointers.
/// ///
/// `T` must be a vector. /// `T` must be a vector.
/// ///
@ -263,7 +263,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_gather<T, U, V>(val: T, ptr: U, mask: V) -> T; pub fn simd_gather<T, U, V>(val: T, ptr: U, mask: V) -> T;
/// Write to a vector of pointers. /// Writes to a vector of pointers.
/// ///
/// `T` must be a vector. /// `T` must be a vector.
/// ///
@ -286,7 +286,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_scatter<T, U, V>(val: T, ptr: U, mask: V); pub fn simd_scatter<T, U, V>(val: T, ptr: U, mask: V);
/// Read a vector of pointers. /// Reads a vector of pointers.
/// ///
/// `T` must be a vector. /// `T` must be a vector.
/// ///
@ -308,7 +308,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_masked_load<V, U, T>(mask: V, ptr: U, val: T) -> T; pub fn simd_masked_load<V, U, T>(mask: V, ptr: U, val: T) -> T;
/// Write to a vector of pointers. /// Writes to a vector of pointers.
/// ///
/// `T` must be a vector. /// `T` must be a vector.
/// ///
@ -329,13 +329,13 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_masked_store<V, U, T>(mask: V, ptr: U, val: T); pub fn simd_masked_store<V, U, T>(mask: V, ptr: U, val: T);
/// Add two simd vectors elementwise, with saturation. /// Adds two simd vectors elementwise, with saturation.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_saturating_add<T>(x: T, y: T) -> T; pub fn simd_saturating_add<T>(x: T, y: T) -> T;
/// Subtract two simd vectors elementwise, with saturation. /// Subtracts two simd vectors elementwise, with saturation.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
/// ///
@ -343,7 +343,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_saturating_sub<T>(lhs: T, rhs: T) -> T; pub fn simd_saturating_sub<T>(lhs: T, rhs: T) -> T;
/// Add elements within a vector from left to right. /// Adds elements within a vector from left to right.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -353,7 +353,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_add_ordered<T, U>(x: T, y: U) -> U; pub fn simd_reduce_add_ordered<T, U>(x: T, y: U) -> U;
/// Add elements within a vector in arbitrary order. May also be re-associated with /// Adds elements within a vector in arbitrary order. May also be re-associated with
/// unordered additions on the inputs/outputs. /// unordered additions on the inputs/outputs.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
@ -362,7 +362,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_add_unordered<T, U>(x: T) -> U; pub fn simd_reduce_add_unordered<T, U>(x: T) -> U;
/// Multiply elements within a vector from left to right. /// Multiplies elements within a vector from left to right.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -372,7 +372,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_mul_ordered<T, U>(x: T, y: U) -> U; pub fn simd_reduce_mul_ordered<T, U>(x: T, y: U) -> U;
/// Multiply elements within a vector in arbitrary order. May also be re-associated with /// Multiplies elements within a vector in arbitrary order. May also be re-associated with
/// unordered additions on the inputs/outputs. /// unordered additions on the inputs/outputs.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
@ -381,7 +381,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_mul_unordered<T, U>(x: T) -> U; pub fn simd_reduce_mul_unordered<T, U>(x: T) -> U;
/// Check if all mask values are true. /// Checks if all mask values are true.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
/// ///
@ -390,7 +390,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_all<T>(x: T) -> bool; pub fn simd_reduce_all<T>(x: T) -> bool;
/// Check if any mask value is true. /// Checks if any mask value is true.
/// ///
/// `T` must be a vector of integer primitive types. /// `T` must be a vector of integer primitive types.
/// ///
@ -399,7 +399,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_any<T>(x: T) -> bool; pub fn simd_reduce_any<T>(x: T) -> bool;
/// Return the maximum element of a vector. /// Returns the maximum element of a vector.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -409,7 +409,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_max<T, U>(x: T) -> U; pub fn simd_reduce_max<T, U>(x: T) -> U;
/// Return the minimum element of a vector. /// Returns the minimum element of a vector.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -419,7 +419,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_min<T, U>(x: T) -> U; pub fn simd_reduce_min<T, U>(x: T) -> U;
/// Logical "and" all elements together. /// Logical "ands" all elements together.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -427,7 +427,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_and<T, U>(x: T) -> U; pub fn simd_reduce_and<T, U>(x: T) -> U;
/// Logical "or" all elements together. /// Logical "ors" all elements together.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -435,7 +435,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_or<T, U>(x: T) -> U; pub fn simd_reduce_or<T, U>(x: T) -> U;
/// Logical "exclusive or" all elements together. /// Logical "exclusive ors" all elements together.
/// ///
/// `T` must be a vector of integer or floating-point primitive types. /// `T` must be a vector of integer or floating-point primitive types.
/// ///
@ -443,7 +443,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_reduce_xor<T, U>(x: T) -> U; pub fn simd_reduce_xor<T, U>(x: T) -> U;
/// Truncate an integer vector to a bitmask. /// Truncates an integer vector to a bitmask.
/// ///
/// `T` must be an integer vector. /// `T` must be an integer vector.
/// ///
@ -479,7 +479,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_bitmask<T, U>(x: T) -> U; pub fn simd_bitmask<T, U>(x: T) -> U;
/// Select elements from a mask. /// Selects elements from a mask.
/// ///
/// `M` must be an integer vector. /// `M` must be an integer vector.
/// ///
@ -494,7 +494,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_select<M, T>(mask: M, if_true: T, if_false: T) -> T; pub fn simd_select<M, T>(mask: M, if_true: T, if_false: T) -> T;
/// Select elements from a bitmask. /// Selects elements from a bitmask.
/// ///
/// `M` must be an unsigned integer or array of `u8`, matching `simd_bitmask`. /// `M` must be an unsigned integer or array of `u8`, matching `simd_bitmask`.
/// ///
@ -511,7 +511,8 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_select_bitmask<M, T>(m: M, yes: T, no: T) -> T; pub fn simd_select_bitmask<M, T>(m: M, yes: T, no: T) -> T;
/// Elementwise calculates the offset from a pointer vector, potentially wrapping. /// Calculates the offset from a pointer vector elementwise, potentially
/// wrapping.
/// ///
/// `T` must be a vector of pointers. /// `T` must be a vector of pointers.
/// ///
@ -521,13 +522,13 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_arith_offset<T, U>(ptr: T, offset: U) -> T; pub fn simd_arith_offset<T, U>(ptr: T, offset: U) -> T;
/// Cast a vector of pointers. /// Casts a vector of pointers.
/// ///
/// `T` and `U` must be vectors of pointers with the same number of elements. /// `T` and `U` must be vectors of pointers with the same number of elements.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_cast_ptr<T, U>(ptr: T) -> U; pub fn simd_cast_ptr<T, U>(ptr: T) -> U;
/// Expose a vector of pointers as a vector of addresses. /// Exposes a vector of pointers as a vector of addresses.
/// ///
/// `T` must be a vector of pointers. /// `T` must be a vector of pointers.
/// ///
@ -535,7 +536,7 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_expose_provenance<T, U>(ptr: T) -> U; pub fn simd_expose_provenance<T, U>(ptr: T) -> U;
/// Create a vector of pointers from a vector of addresses. /// Creates a vector of pointers from a vector of addresses.
/// ///
/// `T` must be a vector of `usize`. /// `T` must be a vector of `usize`.
/// ///
@ -543,56 +544,56 @@ extern "rust-intrinsic" {
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_with_exposed_provenance<T, U>(addr: T) -> U; pub fn simd_with_exposed_provenance<T, U>(addr: T) -> U;
/// Swap bytes of each element. /// Swaps bytes of each element.
/// ///
/// `T` must be a vector of integers. /// `T` must be a vector of integers.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_bswap<T>(x: T) -> T; pub fn simd_bswap<T>(x: T) -> T;
/// Reverse bits of each element. /// Reverses bits of each element.
/// ///
/// `T` must be a vector of integers. /// `T` must be a vector of integers.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_bitreverse<T>(x: T) -> T; pub fn simd_bitreverse<T>(x: T) -> T;
/// Count the leading zeros of each element. /// Counts the leading zeros of each element.
/// ///
/// `T` must be a vector of integers. /// `T` must be a vector of integers.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_ctlz<T>(x: T) -> T; pub fn simd_ctlz<T>(x: T) -> T;
/// Count the number of ones in each element. /// Counts the number of ones in each element.
/// ///
/// `T` must be a vector of integers. /// `T` must be a vector of integers.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_ctpop<T>(x: T) -> T; pub fn simd_ctpop<T>(x: T) -> T;
/// Count the trailing zeros of each element. /// Counts the trailing zeros of each element.
/// ///
/// `T` must be a vector of integers. /// `T` must be a vector of integers.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_cttz<T>(x: T) -> T; pub fn simd_cttz<T>(x: T) -> T;
/// Round up each element to the next highest integer-valued float. /// Rounds up each element to the next highest integer-valued float.
/// ///
/// `T` must be a vector of floats. /// `T` must be a vector of floats.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_ceil<T>(x: T) -> T; pub fn simd_ceil<T>(x: T) -> T;
/// Round down each element to the next lowest integer-valued float. /// Rounds down each element to the next lowest integer-valued float.
/// ///
/// `T` must be a vector of floats. /// `T` must be a vector of floats.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_floor<T>(x: T) -> T; pub fn simd_floor<T>(x: T) -> T;
/// Round each element to the closest integer-valued float. /// Rounds each element to the closest integer-valued float.
/// Ties are resolved by rounding away from 0. /// Ties are resolved by rounding away from 0.
/// ///
/// `T` must be a vector of floats. /// `T` must be a vector of floats.
#[rustc_nounwind] #[rustc_nounwind]
pub fn simd_round<T>(x: T) -> T; pub fn simd_round<T>(x: T) -> T;
/// Return the integer part of each element as an integer-valued float. /// Returns the integer part of each element as an integer-valued float.
/// In other words, non-integer values are truncated towards zero. /// In other words, non-integer values are truncated towards zero.
/// ///
/// `T` must be a vector of floats. /// `T` must be a vector of floats.

10
library/core/src/io/borrowed_buf.rs
View File

@ -44,7 +44,7 @@ impl Debug for BorrowedBuf<'_> {
} }
} }
/// Create a new `BorrowedBuf` from a fully initialized slice. /// Creates a new `BorrowedBuf` from a fully initialized slice.
impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> { impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> {
#[inline] #[inline]
fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> { fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> {
@ -59,7 +59,7 @@ impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> {
} }
} }
/// Create a new `BorrowedBuf` from an uninitialized buffer. /// Creates a new `BorrowedBuf` from an uninitialized buffer.
/// ///
/// Use `set_init` if part of the buffer is known to be already initialized. /// Use `set_init` if part of the buffer is known to be already initialized.
impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data> { impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data> {
@ -174,7 +174,7 @@ pub struct BorrowedCursor<'a> {
} }
impl<'a> BorrowedCursor<'a> { impl<'a> BorrowedCursor<'a> {
/// Reborrow this cursor by cloning it with a smaller lifetime. /// Reborrows this cursor by cloning it with a smaller lifetime.
/// ///
/// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is /// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is
/// not accessible while the new cursor exists. /// not accessible while the new cursor exists.
@ -247,7 +247,7 @@ impl<'a> BorrowedCursor<'a> {
unsafe { self.buf.buf.get_unchecked_mut(self.buf.filled..) } unsafe { self.buf.buf.get_unchecked_mut(self.buf.filled..) }
} }
/// Advance the cursor by asserting that `n` bytes have been filled. /// Advances the cursor by asserting that `n` bytes have been filled.
/// ///
/// After advancing, the `n` bytes are no longer accessible via the cursor and can only be /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
/// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
@ -268,7 +268,7 @@ impl<'a> BorrowedCursor<'a> {
self self
} }
/// Advance the cursor by asserting that `n` bytes have been filled. /// Advances the cursor by asserting that `n` bytes have been filled.
/// ///
/// After advancing, the `n` bytes are no longer accessible via the cursor and can only be /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
/// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements

6
library/core/src/iter/adapters/step_by.rs
View File

@ -414,9 +414,9 @@ unsafe impl<I: DoubleEndedIterator + ExactSizeIterator> StepByBackImpl<I> for St
/// These only work for unsigned types, and will need to be reworked /// These only work for unsigned types, and will need to be reworked
/// if you want to use it to specialize on signed types. /// if you want to use it to specialize on signed types.
/// ///
/// Currently these are only implemented for integers up to usize due to /// Currently these are only implemented for integers up to `usize` due to
/// correctness issues around ExactSizeIterator impls on 16bit platforms. /// correctness issues around `ExactSizeIterator` impls on 16bit platforms.
/// And since ExactSizeIterator is a prerequisite for backwards iteration /// And since `ExactSizeIterator` is a prerequisite for backwards iteration
/// and we must consistently specialize backwards and forwards iteration /// and we must consistently specialize backwards and forwards iteration
/// that makes the situation complicated enough that it's not covered /// that makes the situation complicated enough that it's not covered
/// for now. /// for now.

8
library/core/src/iter/traits/accum.rs
View File

@ -15,8 +15,8 @@ use crate::num::Wrapping;
label = "value of type `{Self}` cannot be made by summing a `std::iter::Iterator<Item={A}>`" label = "value of type `{Self}` cannot be made by summing a `std::iter::Iterator<Item={A}>`"
)] )]
pub trait Sum<A = Self>: Sized { pub trait Sum<A = Self>: Sized {
/// Method which takes an iterator and generates `Self` from the elements by /// Takes an iterator and generates `Self` from the elements by "summing up"
/// "summing up" the items. /// the items.
#[stable(feature = "iter_arith_traits", since = "1.12.0")] #[stable(feature = "iter_arith_traits", since = "1.12.0")]
fn sum<I: Iterator<Item = A>>(iter: I) -> Self; fn sum<I: Iterator<Item = A>>(iter: I) -> Self;
} }
@ -36,8 +36,8 @@ pub trait Sum<A = Self>: Sized {
label = "value of type `{Self}` cannot be made by multiplying all elements from a `std::iter::Iterator<Item={A}>`" label = "value of type `{Self}` cannot be made by multiplying all elements from a `std::iter::Iterator<Item={A}>`"
)] )]
pub trait Product<A = Self>: Sized { pub trait Product<A = Self>: Sized {
/// Method which takes an iterator and generates `Self` from the elements by /// Takes an iterator and generates `Self` from the elements by multiplying
/// multiplying the items. /// the items.
#[stable(feature = "iter_arith_traits", since = "1.12.0")] #[stable(feature = "iter_arith_traits", since = "1.12.0")]
fn product<I: Iterator<Item = A>>(iter: I) -> Self; fn product<I: Iterator<Item = A>>(iter: I) -> Self;
} }

2
library/core/src/macros/mod.rs
View File

@ -633,7 +633,7 @@ macro_rules! write {
}; };
} }
/// Write formatted data into a buffer, with a newline appended. /// Writes formatted data into a buffer, with a newline appended.
/// ///
/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
/// (no additional CARRIAGE RETURN (`\r`/`U+000D`). /// (no additional CARRIAGE RETURN (`\r`/`U+000D`).

2
library/core/src/marker.rs
View File

@ -871,7 +871,7 @@ marker_impls! {
/// ///
/// *However*, you cannot use [`mem::replace`] on `!Unpin` data which is *pinned* by being wrapped /// *However*, you cannot use [`mem::replace`] on `!Unpin` data which is *pinned* by being wrapped
/// inside a [`Pin<Ptr>`] pointing at it. This is because you cannot (safely) use a /// inside a [`Pin<Ptr>`] pointing at it. This is because you cannot (safely) use a
/// [`Pin<Ptr>`] to get an `&mut T` to its pointee value, which you would need to call /// [`Pin<Ptr>`] to get a `&mut T` to its pointee value, which you would need to call
/// [`mem::replace`], and *that* is what makes this system work. /// [`mem::replace`], and *that* is what makes this system work.
/// ///
/// So this, for example, can only be done on types implementing `Unpin`: /// So this, for example, can only be done on types implementing `Unpin`:

10
library/core/src/mem/manually_drop.rs
View File

@ -118,10 +118,12 @@ impl<T> ManuallyDrop<T> {
} }
impl<T: ?Sized> ManuallyDrop<T> { impl<T: ?Sized> ManuallyDrop<T> {
/// Manually drops the contained value. This is exactly equivalent to calling /// Manually drops the contained value.
/// [`ptr::drop_in_place`] with a pointer to the contained value. As such, unless ///
/// the contained value is a packed struct, the destructor will be called in-place /// This is exactly equivalent to calling [`ptr::drop_in_place`] with a
/// without moving the value, and thus can be used to safely drop [pinned] data. /// pointer to the contained value. As such, unless the contained value is a
/// packed struct, the destructor will be called in-place without moving the
/// value, and thus can be used to safely drop [pinned] data.
/// ///
/// If you have ownership of the value, you can use [`ManuallyDrop::into_inner`] instead. /// If you have ownership of the value, you can use [`ManuallyDrop::into_inner`] instead.
/// ///

2
library/core/src/mem/maybe_uninit.rs
View File

@ -310,7 +310,7 @@ impl<T> MaybeUninit<T> {
MaybeUninit { uninit: () } MaybeUninit { uninit: () }
} }
/// Create a new array of `MaybeUninit<T>` items, in an uninitialized state. /// Creates a new array of `MaybeUninit<T>` items, in an uninitialized state.
/// ///
/// Note: in a future Rust version this method may become unnecessary /// Note: in a future Rust version this method may become unnecessary
/// when Rust allows /// when Rust allows

44
library/core/src/net/ip_addr.rs
View File

@ -406,8 +406,8 @@ impl IpAddr {
matches!(self, IpAddr::V6(_)) matches!(self, IpAddr::V6(_))
} }
/// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped IPv6 address, otherwise it /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped IPv6
/// returns `self` as-is. /// address, otherwise returns `self` as-is.
/// ///
/// # Examples /// # Examples
/// ///
@ -549,7 +549,7 @@ impl Ipv4Addr {
#[stable(feature = "ip_constructors", since = "1.30.0")] #[stable(feature = "ip_constructors", since = "1.30.0")]
pub const UNSPECIFIED: Self = Ipv4Addr::new(0, 0, 0, 0); pub const UNSPECIFIED: Self = Ipv4Addr::new(0, 0, 0, 0);
/// An IPv4 address representing the broadcast address: `255.255.255.255` /// An IPv4 address representing the broadcast address: `255.255.255.255`.
/// ///
/// # Examples /// # Examples
/// ///
@ -686,10 +686,10 @@ impl Ipv4Addr {
/// Returns [`true`] if the address appears to be globally reachable /// Returns [`true`] if the address appears to be globally reachable
/// as specified by the [IANA IPv4 Special-Purpose Address Registry]. /// as specified by the [IANA IPv4 Special-Purpose Address Registry].
/// Whether or not an address is practically reachable will depend on your network configuration.
/// ///
/// Most IPv4 addresses are globally reachable; /// Whether or not an address is practically reachable will depend on your
/// unless they are specifically defined as *not* globally reachable. /// network configuration. Most IPv4 addresses are globally reachable, unless
/// they are specifically defined as *not* globally reachable.
/// ///
/// Non-exhaustive list of notable addresses that are not globally reachable: /// Non-exhaustive list of notable addresses that are not globally reachable:
/// ///
@ -802,8 +802,10 @@ impl Ipv4Addr {
} }
/// Returns [`true`] if this address part of the `198.18.0.0/15` range, which is reserved for /// Returns [`true`] if this address part of the `198.18.0.0/15` range, which is reserved for
/// network devices benchmarking. This range is defined in [IETF RFC 2544] as `192.18.0.0` /// network devices benchmarking.
/// through `198.19.255.255` but [errata 423] corrects it to `198.18.0.0/15`. ///
/// This range is defined in [IETF RFC 2544] as `192.18.0.0` through
/// `198.19.255.255` but [errata 423] corrects it to `198.18.0.0/15`.
/// ///
/// [IETF RFC 2544]: https://tools.ietf.org/html/rfc2544 /// [IETF RFC 2544]: https://tools.ietf.org/html/rfc2544
/// [errata 423]: https://www.rfc-editor.org/errata/eid423 /// [errata 423]: https://www.rfc-editor.org/errata/eid423
@ -827,10 +829,12 @@ impl Ipv4Addr {
self.octets()[0] == 198 && (self.octets()[1] & 0xfe) == 18 self.octets()[0] == 198 && (self.octets()[1] & 0xfe) == 18
} }
/// Returns [`true`] if this address is reserved by IANA for future use. [IETF RFC 1112] /// Returns [`true`] if this address is reserved by IANA for future use.
/// defines the block of reserved addresses as `240.0.0.0/4`. This range normally includes the ///
/// broadcast address `255.255.255.255`, but this implementation explicitly excludes it, since /// [IETF RFC 1112] defines the block of reserved addresses as `240.0.0.0/4`.
/// it is obviously not reserved for future use. /// This range normally includes the broadcast address `255.255.255.255`, but
/// this implementation explicitly excludes it, since it is obviously not
/// reserved for future use.
/// ///
/// [IETF RFC 1112]: https://tools.ietf.org/html/rfc1112 /// [IETF RFC 1112]: https://tools.ietf.org/html/rfc1112
/// ///
@ -1328,7 +1332,7 @@ impl Ipv6Addr {
#[stable(feature = "ip_constructors", since = "1.30.0")] #[stable(feature = "ip_constructors", since = "1.30.0")]
pub const LOCALHOST: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1); pub const LOCALHOST: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
/// An IPv6 address representing the unspecified address: `::` /// An IPv6 address representing the unspecified address: `::`.
/// ///
/// This corresponds to constant `IN6ADDR_ANY_INIT` or `in6addr_any` in other languages. /// This corresponds to constant `IN6ADDR_ANY_INIT` or `in6addr_any` in other languages.
/// ///
@ -1424,10 +1428,10 @@ impl Ipv6Addr {
/// Returns [`true`] if the address appears to be globally reachable /// Returns [`true`] if the address appears to be globally reachable
/// as specified by the [IANA IPv6 Special-Purpose Address Registry]. /// as specified by the [IANA IPv6 Special-Purpose Address Registry].
/// Whether or not an address is practically reachable will depend on your network configuration.
/// ///
/// Most IPv6 addresses are globally reachable; /// Whether or not an address is practically reachable will depend on your
/// unless they are specifically defined as *not* globally reachable. /// network configuration. Most IPv6 addresses are globally reachable, unless
/// they are specifically defined as *not* globally reachable.
/// ///
/// Non-exhaustive list of notable addresses that are not globally reachable: /// Non-exhaustive list of notable addresses that are not globally reachable:
/// - The [unspecified address] ([`is_unspecified`](Ipv6Addr::is_unspecified)) /// - The [unspecified address] ([`is_unspecified`](Ipv6Addr::is_unspecified))
@ -1879,8 +1883,8 @@ impl Ipv6Addr {
} }
} }
/// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped address, otherwise it /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped address,
/// returns self wrapped in an `IpAddr::V6`. /// otherwise returns self wrapped in an `IpAddr::V6`.
/// ///
/// # Examples /// # Examples
/// ///
@ -1919,7 +1923,7 @@ impl Ipv6Addr {
} }
} }
/// Write an Ipv6Addr, conforming to the canonical style described by /// Writes an Ipv6Addr, conforming to the canonical style described by
/// [RFC 5952](https://tools.ietf.org/html/rfc5952). /// [RFC 5952](https://tools.ietf.org/html/rfc5952).
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for Ipv6Addr { impl fmt::Display for Ipv6Addr {
@ -1962,7 +1966,7 @@ impl fmt::Display for Ipv6Addr {
longest longest
}; };
/// Write a colon-separated part of the address /// Writes a colon-separated part of the address.
#[inline] #[inline]
fn fmt_subslice(f: &mut fmt::Formatter<'_>, chunk: &[u16]) -> fmt::Result { fn fmt_subslice(f: &mut fmt::Formatter<'_>, chunk: &[u16]) -> fmt::Result {
if let Some((first, tail)) = chunk.split_first() { if let Some((first, tail)) = chunk.split_first() {

20
library/core/src/net/parser.rs
View File

@ -68,7 +68,7 @@ impl<'a> Parser<'a> {
self.state.first().map(|&b| char::from(b)) self.state.first().map(|&b| char::from(b))
} }
/// Read the next character from the input /// Reads the next character from the input
fn read_char(&mut self) -> Option<char> { fn read_char(&mut self) -> Option<char> {
self.state.split_first().map(|(&b, tail)| { self.state.split_first().map(|(&b, tail)| {
self.state = tail; self.state = tail;
@ -77,7 +77,7 @@ impl<'a> Parser<'a> {
} }
#[must_use] #[must_use]
/// Read the next character from the input if it matches the target. /// Reads the next character from the input if it matches the target.
fn read_given_char(&mut self, target: char) -> Option<()> { fn read_given_char(&mut self, target: char) -> Option<()> {
self.read_atomically(|p| { self.read_atomically(|p| {
p.read_char().and_then(|c| if c == target { Some(()) } else { None }) p.read_char().and_then(|c| if c == target { Some(()) } else { None })
@ -165,7 +165,7 @@ impl<'a> Parser<'a> {
} }
} }
/// Read an IPv4 address. /// Reads an IPv4 address.
fn read_ipv4_addr(&mut self) -> Option<Ipv4Addr> { fn read_ipv4_addr(&mut self) -> Option<Ipv4Addr> {
self.read_atomically(|p| { self.read_atomically(|p| {
let mut groups = [0; 4]; let mut groups = [0; 4];
@ -182,7 +182,7 @@ impl<'a> Parser<'a> {
}) })
} }
/// Read an IPv6 Address. /// Reads an IPv6 address.
fn read_ipv6_addr(&mut self) -> Option<Ipv6Addr> { fn read_ipv6_addr(&mut self) -> Option<Ipv6Addr> {
/// Read a chunk of an IPv6 address into `groups`. Returns the number /// Read a chunk of an IPv6 address into `groups`. Returns the number
/// of groups read, along with a bool indicating if an embedded /// of groups read, along with a bool indicating if an embedded
@ -249,12 +249,12 @@ impl<'a> Parser<'a> {
}) })
} }
/// Read an IP Address, either IPv4 or IPv6. /// Reads an IP address, either IPv4 or IPv6.
fn read_ip_addr(&mut self) -> Option<IpAddr> { fn read_ip_addr(&mut self) -> Option<IpAddr> {
self.read_ipv4_addr().map(IpAddr::V4).or_else(move || self.read_ipv6_addr().map(IpAddr::V6)) self.read_ipv4_addr().map(IpAddr::V4).or_else(move || self.read_ipv6_addr().map(IpAddr::V6))
} }
/// Read a `:` followed by a port in base 10. /// Reads a `:` followed by a port in base 10.
fn read_port(&mut self) -> Option<u16> { fn read_port(&mut self) -> Option<u16> {
self.read_atomically(|p| { self.read_atomically(|p| {
p.read_given_char(':')?; p.read_given_char(':')?;
@ -262,7 +262,7 @@ impl<'a> Parser<'a> {
}) })
} }
/// Read a `%` followed by a scope ID in base 10. /// Reads a `%` followed by a scope ID in base 10.
fn read_scope_id(&mut self) -> Option<u32> { fn read_scope_id(&mut self) -> Option<u32> {
self.read_atomically(|p| { self.read_atomically(|p| {
p.read_given_char('%')?; p.read_given_char('%')?;
@ -270,7 +270,7 @@ impl<'a> Parser<'a> {
}) })
} }
/// Read an IPv4 address with a port. /// Reads an IPv4 address with a port.
fn read_socket_addr_v4(&mut self) -> Option<SocketAddrV4> { fn read_socket_addr_v4(&mut self) -> Option<SocketAddrV4> {
self.read_atomically(|p| { self.read_atomically(|p| {
let ip = p.read_ipv4_addr()?; let ip = p.read_ipv4_addr()?;
@ -279,7 +279,7 @@ impl<'a> Parser<'a> {
}) })
} }
/// Read an IPv6 address with a port. /// Reads an IPv6 address with a port.
fn read_socket_addr_v6(&mut self) -> Option<SocketAddrV6> { fn read_socket_addr_v6(&mut self) -> Option<SocketAddrV6> {
self.read_atomically(|p| { self.read_atomically(|p| {
p.read_given_char('[')?; p.read_given_char('[')?;
@ -292,7 +292,7 @@ impl<'a> Parser<'a> {
}) })
} }
/// Read an IP address with a port /// Reads an IP address with a port.
fn read_socket_addr(&mut self) -> Option<SocketAddr> { fn read_socket_addr(&mut self) -> Option<SocketAddr> {
self.read_socket_addr_v4() self.read_socket_addr_v4()
.map(SocketAddr::V4) .map(SocketAddr::V4)

4
library/core/src/num/dec2flt/common.rs
View File

@ -2,10 +2,10 @@
/// Helper methods to process immutable bytes. /// Helper methods to process immutable bytes.
pub(crate) trait ByteSlice { pub(crate) trait ByteSlice {
/// Read 8 bytes as a 64-bit integer in little-endian order. /// Reads 8 bytes as a 64-bit integer in little-endian order.
fn read_u64(&self) -> u64; fn read_u64(&self) -> u64;
/// Write a 64-bit integer as 8 bytes in little-endian order. /// Writes a 64-bit integer as 8 bytes in little-endian order.
fn write_u64(&mut self, value: u64); fn write_u64(&mut self, value: u64);
/// Calculate the offset of a slice from another. /// Calculate the offset of a slice from another.

4
library/core/src/num/dec2flt/float.rs
View File

@ -81,7 +81,7 @@ pub trait RawFloat:
// Maximum mantissa for the fast-path (`1 << 53` for f64). // Maximum mantissa for the fast-path (`1 << 53` for f64).
const MAX_MANTISSA_FAST_PATH: u64 = 2_u64 << Self::MANTISSA_EXPLICIT_BITS; const MAX_MANTISSA_FAST_PATH: u64 = 2_u64 << Self::MANTISSA_EXPLICIT_BITS;
/// Convert integer into float through an as cast. /// Converts integer into float through an as cast.
/// This is only called in the fast-path algorithm, and therefore /// This is only called in the fast-path algorithm, and therefore
/// will not lose precision, since the value will always have /// will not lose precision, since the value will always have
/// only if the value is <= Self::MAX_MANTISSA_FAST_PATH. /// only if the value is <= Self::MAX_MANTISSA_FAST_PATH.
@ -90,7 +90,7 @@ pub trait RawFloat:
/// Performs a raw transmutation from an integer. /// Performs a raw transmutation from an integer.
fn from_u64_bits(v: u64) -> Self; fn from_u64_bits(v: u64) -> Self;
/// Get a small power-of-ten for fast-path multiplication. /// Gets a small power-of-ten for fast-path multiplication.
fn pow10_fast_path(exponent: usize) -> Self; fn pow10_fast_path(exponent: usize) -> Self;
/// Returns the category that this number falls into. /// Returns the category that this number falls into.

14
library/core/src/num/f128.rs
View File

@ -898,7 +898,7 @@ impl f128 {
intrinsics::const_eval_select((v,), ct_u128_to_f128, rt_u128_to_f128) intrinsics::const_eval_select((v,), ct_u128_to_f128, rt_u128_to_f128)
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// big-endian (network) byte order. /// big-endian (network) byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -924,7 +924,7 @@ impl f128 {
self.to_bits().to_be_bytes() self.to_bits().to_be_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// little-endian byte order. /// little-endian byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -950,7 +950,7 @@ impl f128 {
self.to_bits().to_le_bytes() self.to_bits().to_le_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// native byte order. /// native byte order.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
@ -987,7 +987,7 @@ impl f128 {
self.to_bits().to_ne_bytes() self.to_bits().to_ne_bytes()
} }
/// Create a floating point value from its representation as a byte array in big endian. /// Creates a floating point value from its representation as a byte array in big endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1014,7 +1014,7 @@ impl f128 {
Self::from_bits(u128::from_be_bytes(bytes)) Self::from_bits(u128::from_be_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in little endian. /// Creates a floating point value from its representation as a byte array in little endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1041,7 +1041,7 @@ impl f128 {
Self::from_bits(u128::from_le_bytes(bytes)) Self::from_bits(u128::from_le_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in native endian. /// Creates a floating point value from its representation as a byte array in native endian.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
/// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
@ -1078,7 +1078,7 @@ impl f128 {
Self::from_bits(u128::from_ne_bytes(bytes)) Self::from_bits(u128::from_ne_bytes(bytes))
} }
/// Return the ordering between `self` and `other`. /// Returns the ordering between `self` and `other`.
/// ///
/// Unlike the standard partial comparison between floating point numbers, /// Unlike the standard partial comparison between floating point numbers,
/// this comparison always produces an ordering in accordance to /// this comparison always produces an ordering in accordance to

14
library/core/src/num/f16.rs
View File

@ -933,7 +933,7 @@ impl f16 {
intrinsics::const_eval_select((v,), ct_u16_to_f16, rt_u16_to_f16) intrinsics::const_eval_select((v,), ct_u16_to_f16, rt_u16_to_f16)
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// big-endian (network) byte order. /// big-endian (network) byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -958,7 +958,7 @@ impl f16 {
self.to_bits().to_be_bytes() self.to_bits().to_be_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// little-endian byte order. /// little-endian byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -983,7 +983,7 @@ impl f16 {
self.to_bits().to_le_bytes() self.to_bits().to_le_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// native byte order. /// native byte order.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
@ -1021,7 +1021,7 @@ impl f16 {
self.to_bits().to_ne_bytes() self.to_bits().to_ne_bytes()
} }
/// Create a floating point value from its representation as a byte array in big endian. /// Creates a floating point value from its representation as a byte array in big endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1044,7 +1044,7 @@ impl f16 {
Self::from_bits(u16::from_be_bytes(bytes)) Self::from_bits(u16::from_be_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in little endian. /// Creates a floating point value from its representation as a byte array in little endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1067,7 +1067,7 @@ impl f16 {
Self::from_bits(u16::from_le_bytes(bytes)) Self::from_bits(u16::from_le_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in native endian. /// Creates a floating point value from its representation as a byte array in native endian.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
/// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
@ -1101,7 +1101,7 @@ impl f16 {
Self::from_bits(u16::from_ne_bytes(bytes)) Self::from_bits(u16::from_ne_bytes(bytes))
} }
/// Return the ordering between `self` and `other`. /// Returns the ordering between `self` and `other`.
/// ///
/// Unlike the standard partial comparison between floating point numbers, /// Unlike the standard partial comparison between floating point numbers,
/// this comparison always produces an ordering in accordance to /// this comparison always produces an ordering in accordance to

38
library/core/src/num/f32.rs
View File

@ -721,11 +721,13 @@ impl f32 {
} }
/// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
/// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any /// positive sign bit and positive infinity.
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that ///
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of /// Note that IEEE 754 doesn't assign any meaning to the sign bit in case of
/// `is_sign_positive` on a NaN might produce an unexpected result in some cases. /// a NaN, and as Rust doesn't guarantee that the bit pattern of NaNs are
/// See [explanation of NaN as a special value](f32) for more info. /// conserved over arithmetic operations, the result of `is_sign_positive` on
/// a NaN might produce an unexpected result in some cases. See [explanation
/// of NaN as a special value](f32) for more info.
/// ///
/// ``` /// ```
/// let f = 7.0_f32; /// let f = 7.0_f32;
@ -743,11 +745,13 @@ impl f32 {
} }
/// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with
/// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any /// negative sign bit and negative infinity.
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that ///
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of /// Note that IEEE 754 doesn't assign any meaning to the sign bit in case of
/// `is_sign_negative` on a NaN might produce an unexpected result in some cases. /// a NaN, and as Rust doesn't guarantee that the bit pattern of NaNs are
/// See [explanation of NaN as a special value](f32) for more info. /// conserved over arithmetic operations, the result of `is_sign_negative` on
/// a NaN might produce an unexpected result in some cases. See [explanation
/// of NaN as a special value](f32) for more info.
/// ///
/// ``` /// ```
/// let f = 7.0f32; /// let f = 7.0f32;
@ -1274,7 +1278,7 @@ impl f32 {
intrinsics::const_eval_select((v,), ct_u32_to_f32, rt_u32_to_f32) intrinsics::const_eval_select((v,), ct_u32_to_f32, rt_u32_to_f32)
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// big-endian (network) byte order. /// big-endian (network) byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -1295,7 +1299,7 @@ impl f32 {
self.to_bits().to_be_bytes() self.to_bits().to_be_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// little-endian byte order. /// little-endian byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -1316,7 +1320,7 @@ impl f32 {
self.to_bits().to_le_bytes() self.to_bits().to_le_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// native byte order. /// native byte order.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
@ -1350,7 +1354,7 @@ impl f32 {
self.to_bits().to_ne_bytes() self.to_bits().to_ne_bytes()
} }
/// Create a floating point value from its representation as a byte array in big endian. /// Creates a floating point value from its representation as a byte array in big endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1369,7 +1373,7 @@ impl f32 {
Self::from_bits(u32::from_be_bytes(bytes)) Self::from_bits(u32::from_be_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in little endian. /// Creates a floating point value from its representation as a byte array in little endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1388,7 +1392,7 @@ impl f32 {
Self::from_bits(u32::from_le_bytes(bytes)) Self::from_bits(u32::from_le_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in native endian. /// Creates a floating point value from its representation as a byte array in native endian.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
/// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
@ -1418,7 +1422,7 @@ impl f32 {
Self::from_bits(u32::from_ne_bytes(bytes)) Self::from_bits(u32::from_ne_bytes(bytes))
} }
/// Return the ordering between `self` and `other`. /// Returns the ordering between `self` and `other`.
/// ///
/// Unlike the standard partial comparison between floating point numbers, /// Unlike the standard partial comparison between floating point numbers,
/// this comparison always produces an ordering in accordance to /// this comparison always produces an ordering in accordance to

38
library/core/src/num/f64.rs
View File

@ -711,11 +711,13 @@ impl f64 {
} }
/// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
/// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any /// positive sign bit and positive infinity.
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that ///
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of /// Note that IEEE 754 doesn't assign any meaning to the sign bit in case of
/// `is_sign_positive` on a NaN might produce an unexpected result in some cases. /// a NaN, and as Rust doesn't guarantee that the bit pattern of NaNs are
/// See [explanation of NaN as a special value](f32) for more info. /// conserved over arithmetic operations, the result of `is_sign_positive` on
/// a NaN might produce an unexpected result in some cases. See [explanation
/// of NaN as a special value](f32) for more info.
/// ///
/// ``` /// ```
/// let f = 7.0_f64; /// let f = 7.0_f64;
@ -742,11 +744,13 @@ impl f64 {
} }
/// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with
/// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any /// negative sign bit and negative infinity.
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that ///
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of /// Note that IEEE 754 doesn't assign any meaning to the sign bit in case of
/// `is_sign_negative` on a NaN might produce an unexpected result in some cases. /// a NaN, and as Rust doesn't guarantee that the bit pattern of NaNs are
/// See [explanation of NaN as a special value](f32) for more info. /// conserved over arithmetic operations, the result of `is_sign_negative` on
/// a NaN might produce an unexpected result in some cases. See [explanation
/// of NaN as a special value](f32) for more info.
/// ///
/// ``` /// ```
/// let f = 7.0_f64; /// let f = 7.0_f64;
@ -1252,7 +1256,7 @@ impl f64 {
intrinsics::const_eval_select((v,), ct_u64_to_f64, rt_u64_to_f64) intrinsics::const_eval_select((v,), ct_u64_to_f64, rt_u64_to_f64)
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// big-endian (network) byte order. /// big-endian (network) byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -1273,7 +1277,7 @@ impl f64 {
self.to_bits().to_be_bytes() self.to_bits().to_be_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// little-endian byte order. /// little-endian byte order.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
@ -1294,7 +1298,7 @@ impl f64 {
self.to_bits().to_le_bytes() self.to_bits().to_le_bytes()
} }
/// Return the memory representation of this floating point number as a byte array in /// Returns the memory representation of this floating point number as a byte array in
/// native byte order. /// native byte order.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
@ -1328,7 +1332,7 @@ impl f64 {
self.to_bits().to_ne_bytes() self.to_bits().to_ne_bytes()
} }
/// Create a floating point value from its representation as a byte array in big endian. /// Creates a floating point value from its representation as a byte array in big endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1347,7 +1351,7 @@ impl f64 {
Self::from_bits(u64::from_be_bytes(bytes)) Self::from_bits(u64::from_be_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in little endian. /// Creates a floating point value from its representation as a byte array in little endian.
/// ///
/// See [`from_bits`](Self::from_bits) for some discussion of the /// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues). /// portability of this operation (there are almost no issues).
@ -1366,7 +1370,7 @@ impl f64 {
Self::from_bits(u64::from_le_bytes(bytes)) Self::from_bits(u64::from_le_bytes(bytes))
} }
/// Create a floating point value from its representation as a byte array in native endian. /// Creates a floating point value from its representation as a byte array in native endian.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
/// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
@ -1396,7 +1400,7 @@ impl f64 {
Self::from_bits(u64::from_ne_bytes(bytes)) Self::from_bits(u64::from_ne_bytes(bytes))
} }
/// Return the ordering between `self` and `other`. /// Returns the ordering between `self` and `other`.
/// ///
/// Unlike the standard partial comparison between floating point numbers, /// Unlike the standard partial comparison between floating point numbers,
/// this comparison always produces an ordering in accordance to /// this comparison always produces an ordering in accordance to

21
library/core/src/num/int_macros.rs
View File

@ -2196,10 +2196,11 @@ macro_rules! int_impl {
acc.wrapping_mul(base) acc.wrapping_mul(base)
} }
/// Calculates `self` + `rhs` /// Calculates `self` + `rhs`.
/// ///
/// Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would /// Returns a tuple of the addition along with a boolean indicating
/// occur. If an overflow would have occurred then the wrapped value is returned. /// whether an arithmetic overflow would occur. If an overflow would have
/// occurred then the wrapped value is returned.
/// ///
/// # Examples /// # Examples
/// ///
@ -2277,7 +2278,7 @@ macro_rules! int_impl {
(c, b != d) (c, b != d)
} }
/// Calculates `self` + `rhs` with an unsigned `rhs` /// Calculates `self` + `rhs` with an unsigned `rhs`.
/// ///
/// Returns a tuple of the addition along with a boolean indicating /// Returns a tuple of the addition along with a boolean indicating
/// whether an arithmetic overflow would occur. If an overflow would /// whether an arithmetic overflow would occur. If an overflow would
@ -3389,7 +3390,7 @@ macro_rules! int_impl {
#[inline(always)] #[inline(always)]
pub const fn is_negative(self) -> bool { self < 0 } pub const fn is_negative(self) -> bool { self < 0 }
/// Return the memory representation of this integer as a byte array in /// Returns the memory representation of this integer as a byte array in
/// big-endian (network) byte order. /// big-endian (network) byte order.
/// ///
#[doc = $to_xe_bytes_doc] #[doc = $to_xe_bytes_doc]
@ -3409,7 +3410,7 @@ macro_rules! int_impl {
self.to_be().to_ne_bytes() self.to_be().to_ne_bytes()
} }
/// Return the memory representation of this integer as a byte array in /// Returns the memory representation of this integer as a byte array in
/// little-endian byte order. /// little-endian byte order.
/// ///
#[doc = $to_xe_bytes_doc] #[doc = $to_xe_bytes_doc]
@ -3429,7 +3430,7 @@ macro_rules! int_impl {
self.to_le().to_ne_bytes() self.to_le().to_ne_bytes()
} }
/// Return the memory representation of this integer as a byte array in /// Returns the memory representation of this integer as a byte array in
/// native byte order. /// native byte order.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
@ -3467,7 +3468,7 @@ macro_rules! int_impl {
unsafe { mem::transmute(self) } unsafe { mem::transmute(self) }
} }
/// Create an integer value from its representation as a byte array in /// Creates an integer value from its representation as a byte array in
/// big endian. /// big endian.
/// ///
#[doc = $from_xe_bytes_doc] #[doc = $from_xe_bytes_doc]
@ -3496,7 +3497,7 @@ macro_rules! int_impl {
Self::from_be(Self::from_ne_bytes(bytes)) Self::from_be(Self::from_ne_bytes(bytes))
} }
/// Create an integer value from its representation as a byte array in /// Creates an integer value from its representation as a byte array in
/// little endian. /// little endian.
/// ///
#[doc = $from_xe_bytes_doc] #[doc = $from_xe_bytes_doc]
@ -3525,7 +3526,7 @@ macro_rules! int_impl {
Self::from_le(Self::from_ne_bytes(bytes)) Self::from_le(Self::from_ne_bytes(bytes))
} }
/// Create an integer value from its memory representation as a byte /// Creates an integer value from its memory representation as a byte
/// array in native endianness. /// array in native endianness.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code

106
library/core/src/num/uint_macros.rs
View File

@ -949,10 +949,10 @@ macro_rules! uint_impl {
} }
/// Strict integer division. Computes `self / rhs`. /// Strict integer division. Computes `self / rhs`.
/// Strict division on unsigned types is just normal division. ///
/// There's no way overflow could ever happen. /// Strict division on unsigned types is just normal division. There's no
/// This function exists, so that all operations /// way overflow could ever happen. This function exists so that all
/// are accounted for in the strict operations. /// operations are accounted for in the strict operations.
/// ///
/// # Panics /// # Panics
/// ///
@ -1008,12 +1008,11 @@ macro_rules! uint_impl {
} }
/// Strict Euclidean division. Computes `self.div_euclid(rhs)`. /// Strict Euclidean division. Computes `self.div_euclid(rhs)`.
/// Strict division on unsigned types is just normal division. ///
/// There's no way overflow could ever happen. /// Strict division on unsigned types is just normal division. There's no
/// This function exists, so that all operations /// way overflow could ever happen. This function exists so that all
/// are accounted for in the strict operations. /// operations are accounted for in the strict operations. Since, for the
/// Since, for the positive integers, all common /// positive integers, all common definitions of division are equal, this
/// definitions of division are equal, this
/// is exactly equal to `self.strict_div(rhs)`. /// is exactly equal to `self.strict_div(rhs)`.
/// ///
/// # Panics /// # Panics
@ -1071,11 +1070,11 @@ macro_rules! uint_impl {
} }
/// Strict integer remainder. Computes `self % rhs`. /// Strict integer remainder. Computes `self % rhs`.
/// Strict remainder calculation on unsigned types is ///
/// just the regular remainder calculation. /// Strict remainder calculation on unsigned types is just the regular
/// There's no way overflow could ever happen. /// remainder calculation. There's no way overflow could ever happen.
/// This function exists, so that all operations /// This function exists so that all operations are accounted for in the
/// are accounted for in the strict operations. /// strict operations.
/// ///
/// # Panics /// # Panics
/// ///
@ -1131,14 +1130,13 @@ macro_rules! uint_impl {
} }
/// Strict Euclidean modulo. Computes `self.rem_euclid(rhs)`. /// Strict Euclidean modulo. Computes `self.rem_euclid(rhs)`.
/// Strict modulo calculation on unsigned types is ///
/// just the regular remainder calculation. /// Strict modulo calculation on unsigned types is just the regular
/// There's no way overflow could ever happen. /// remainder calculation. There's no way overflow could ever happen.
/// This function exists, so that all operations /// This function exists so that all operations are accounted for in the
/// are accounted for in the strict operations. /// strict operations. Since, for the positive integers, all common
/// Since, for the positive integers, all common /// definitions of division are equal, this is exactly equal to
/// definitions of division are equal, this /// `self.strict_rem(rhs)`.
/// is exactly equal to `self.strict_rem(rhs)`.
/// ///
/// # Panics /// # Panics
/// ///
@ -1914,10 +1912,10 @@ macro_rules! uint_impl {
} }
/// Wrapping (modular) division. Computes `self / rhs`. /// Wrapping (modular) division. Computes `self / rhs`.
/// Wrapped division on unsigned types is just normal division. ///
/// There's no way wrapping could ever happen. /// Wrapped division on unsigned types is just normal division. There's
/// This function exists, so that all operations /// no way wrapping could ever happen. This function exists so that all
/// are accounted for in the wrapping operations. /// operations are accounted for in the wrapping operations.
/// ///
/// # Panics /// # Panics
/// ///
@ -1941,13 +1939,12 @@ macro_rules! uint_impl {
} }
/// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`. /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`.
/// Wrapped division on unsigned types is just normal division. ///
/// There's no way wrapping could ever happen. /// Wrapped division on unsigned types is just normal division. There's
/// This function exists, so that all operations /// no way wrapping could ever happen. This function exists so that all
/// are accounted for in the wrapping operations. /// operations are accounted for in the wrapping operations. Since, for
/// Since, for the positive integers, all common /// the positive integers, all common definitions of division are equal,
/// definitions of division are equal, this /// this is exactly equal to `self.wrapping_div(rhs)`.
/// is exactly equal to `self.wrapping_div(rhs)`.
/// ///
/// # Panics /// # Panics
/// ///
@ -1971,11 +1968,11 @@ macro_rules! uint_impl {
} }
/// Wrapping (modular) remainder. Computes `self % rhs`. /// Wrapping (modular) remainder. Computes `self % rhs`.
/// Wrapped remainder calculation on unsigned types is ///
/// just the regular remainder calculation. /// Wrapped remainder calculation on unsigned types is just the regular
/// There's no way wrapping could ever happen. /// remainder calculation. There's no way wrapping could ever happen.
/// This function exists, so that all operations /// This function exists so that all operations are accounted for in the
/// are accounted for in the wrapping operations. /// wrapping operations.
/// ///
/// # Panics /// # Panics
/// ///
@ -1999,14 +1996,13 @@ macro_rules! uint_impl {
} }
/// Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`. /// Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`.
/// Wrapped modulo calculation on unsigned types is ///
/// just the regular remainder calculation. /// Wrapped modulo calculation on unsigned types is just the regular
/// There's no way wrapping could ever happen. /// remainder calculation. There's no way wrapping could ever happen.
/// This function exists, so that all operations /// This function exists so that all operations are accounted for in the
/// are accounted for in the wrapping operations. /// wrapping operations. Since, for the positive integers, all common
/// Since, for the positive integers, all common /// definitions of division are equal, this is exactly equal to
/// definitions of division are equal, this /// `self.wrapping_rem(rhs)`.
/// is exactly equal to `self.wrapping_rem(rhs)`.
/// ///
/// # Panics /// # Panics
/// ///
@ -2162,7 +2158,7 @@ macro_rules! uint_impl {
acc.wrapping_mul(base) acc.wrapping_mul(base)
} }
/// Calculates `self` + `rhs` /// Calculates `self` + `rhs`.
/// ///
/// Returns a tuple of the addition along with a boolean indicating /// Returns a tuple of the addition along with a boolean indicating
/// whether an arithmetic overflow would occur. If an overflow would /// whether an arithmetic overflow would occur. If an overflow would
@ -2236,7 +2232,7 @@ macro_rules! uint_impl {
(c, b || d) (c, b || d)
} }
/// Calculates `self` + `rhs` with a signed `rhs` /// Calculates `self` + `rhs` with a signed `rhs`.
/// ///
/// Returns a tuple of the addition along with a boolean indicating /// Returns a tuple of the addition along with a boolean indicating
/// whether an arithmetic overflow would occur. If an overflow would /// whether an arithmetic overflow would occur. If an overflow would
@ -2967,7 +2963,7 @@ macro_rules! uint_impl {
self.one_less_than_next_power_of_two().wrapping_add(1) self.one_less_than_next_power_of_two().wrapping_add(1)
} }
/// Return the memory representation of this integer as a byte array in /// Returns the memory representation of this integer as a byte array in
/// big-endian (network) byte order. /// big-endian (network) byte order.
/// ///
#[doc = $to_xe_bytes_doc] #[doc = $to_xe_bytes_doc]
@ -2987,7 +2983,7 @@ macro_rules! uint_impl {
self.to_be().to_ne_bytes() self.to_be().to_ne_bytes()
} }
/// Return the memory representation of this integer as a byte array in /// Returns the memory representation of this integer as a byte array in
/// little-endian byte order. /// little-endian byte order.
/// ///
#[doc = $to_xe_bytes_doc] #[doc = $to_xe_bytes_doc]
@ -3007,7 +3003,7 @@ macro_rules! uint_impl {
self.to_le().to_ne_bytes() self.to_le().to_ne_bytes()
} }
/// Return the memory representation of this integer as a byte array in /// Returns the memory representation of this integer as a byte array in
/// native byte order. /// native byte order.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code
@ -3045,7 +3041,7 @@ macro_rules! uint_impl {
unsafe { mem::transmute(self) } unsafe { mem::transmute(self) }
} }
/// Create a native endian integer value from its representation /// Creates a native endian integer value from its representation
/// as a byte array in big endian. /// as a byte array in big endian.
/// ///
#[doc = $from_xe_bytes_doc] #[doc = $from_xe_bytes_doc]
@ -3074,7 +3070,7 @@ macro_rules! uint_impl {
Self::from_be(Self::from_ne_bytes(bytes)) Self::from_be(Self::from_ne_bytes(bytes))
} }
/// Create a native endian integer value from its representation /// Creates a native endian integer value from its representation
/// as a byte array in little endian. /// as a byte array in little endian.
/// ///
#[doc = $from_xe_bytes_doc] #[doc = $from_xe_bytes_doc]
@ -3103,7 +3099,7 @@ macro_rules! uint_impl {
Self::from_le(Self::from_ne_bytes(bytes)) Self::from_le(Self::from_ne_bytes(bytes))
} }
/// Create a native endian integer value from its memory representation /// Creates a native endian integer value from its memory representation
/// as a byte array in native endianness. /// as a byte array in native endianness.
/// ///
/// As the target platform's native endianness is used, portable code /// As the target platform's native endianness is used, portable code

4
library/core/src/ops/control_flow.rs
View File

@ -238,7 +238,7 @@ impl<B, C> ControlFlow<B, C> {
/// They have mediocre names and non-obvious semantics, so aren't /// They have mediocre names and non-obvious semantics, so aren't
/// currently on a path to potential stabilization. /// currently on a path to potential stabilization.
impl<R: ops::Try> ControlFlow<R, R::Output> { impl<R: ops::Try> ControlFlow<R, R::Output> {
/// Create a `ControlFlow` from any type implementing `Try`. /// Creates a `ControlFlow` from any type implementing `Try`.
#[inline] #[inline]
pub(crate) fn from_try(r: R) -> Self { pub(crate) fn from_try(r: R) -> Self {
match R::branch(r) { match R::branch(r) {
@ -247,7 +247,7 @@ impl<R: ops::Try> ControlFlow<R, R::Output> {
} }
} }
/// Convert a `ControlFlow` into any type implementing `Try`; /// Converts a `ControlFlow` into any type implementing `Try`.
#[inline] #[inline]
pub(crate) fn into_try(self) -> R { pub(crate) fn into_try(self) -> R {
match self { match self {

2
library/core/src/panic.rs
View File

@ -160,7 +160,7 @@ pub unsafe trait PanicPayload: crate::fmt::Display {
/// Just borrow the contents. /// Just borrow the contents.
fn get(&mut self) -> &(dyn Any + Send); fn get(&mut self) -> &(dyn Any + Send);
/// Try to borrow the contents as `&str`, if possible without doing any allocations. /// Tries to borrow the contents as `&str`, if possible without doing any allocations.
fn as_str(&mut self) -> Option<&str> { fn as_str(&mut self) -> Option<&str> {
None None
} }

2
library/core/src/panic/panic_info.rs
View File

@ -152,7 +152,7 @@ impl Display for PanicInfo<'_> {
} }
impl<'a> PanicMessage<'a> { impl<'a> PanicMessage<'a> {
/// Get the formatted message, if it has no arguments to be formatted at runtime. /// Gets the formatted message, if it has no arguments to be formatted at runtime.
/// ///
/// This can be used to avoid allocations in some cases. /// This can be used to avoid allocations in some cases.
/// ///

6
library/core/src/panicking.rs
View File

@ -294,10 +294,11 @@ fn panic_misaligned_pointer_dereference(required: usize, found: usize) -> ! {
) )
} }
/// Panic because we cannot unwind out of a function. /// Panics because we cannot unwind out of a function.
/// ///
/// This is a separate function to avoid the codesize impact of each crate containing the string to /// This is a separate function to avoid the codesize impact of each crate containing the string to
/// pass to `panic_nounwind`. /// pass to `panic_nounwind`.
///
/// This function is called directly by the codegen backend, and must not have /// This function is called directly by the codegen backend, and must not have
/// any extra arguments (including those synthesized by track_caller). /// any extra arguments (including those synthesized by track_caller).
#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)]
@ -309,10 +310,11 @@ fn panic_cannot_unwind() -> ! {
panic_nounwind("panic in a function that cannot unwind") panic_nounwind("panic in a function that cannot unwind")
} }
/// Panic because we are unwinding out of a destructor during cleanup. /// Panics because we are unwinding out of a destructor during cleanup.
/// ///
/// This is a separate function to avoid the codesize impact of each crate containing the string to /// This is a separate function to avoid the codesize impact of each crate containing the string to
/// pass to `panic_nounwind`. /// pass to `panic_nounwind`.
///
/// This function is called directly by the codegen backend, and must not have /// This function is called directly by the codegen backend, and must not have
/// any extra arguments (including those synthesized by track_caller). /// any extra arguments (including those synthesized by track_caller).
#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)]

16
library/core/src/pin.rs
View File

@ -421,7 +421,7 @@
//! } //! }
//! //!
//! impl Unmovable { //! impl Unmovable {
//! /// Create a new `Unmovable`. //! /// Creates a new `Unmovable`.
//! /// //! ///
//! /// To ensure the data doesn't move we place it on the heap behind a pinning Box. //! /// To ensure the data doesn't move we place it on the heap behind a pinning Box.
//! /// Note that the data is pinned, but the `Pin<Box<Self>>` which is pinning it can //! /// Note that the data is pinned, but the `Pin<Box<Self>>` which is pinning it can
@ -1168,7 +1168,7 @@ impl<Ptr: Deref<Target: Hash>> Hash for Pin<Ptr> {
} }
impl<Ptr: Deref<Target: Unpin>> Pin<Ptr> { impl<Ptr: Deref<Target: Unpin>> Pin<Ptr> {
/// Construct a new `Pin<Ptr>` around a pointer to some data of a type that /// Constructs a new `Pin<Ptr>` around a pointer to some data of a type that
/// implements [`Unpin`]. /// implements [`Unpin`].
/// ///
/// Unlike `Pin::new_unchecked`, this method is safe because the pointer /// Unlike `Pin::new_unchecked`, this method is safe because the pointer
@ -1223,7 +1223,7 @@ impl<Ptr: Deref<Target: Unpin>> Pin<Ptr> {
} }
impl<Ptr: Deref> Pin<Ptr> { impl<Ptr: Deref> Pin<Ptr> {
/// Construct a new `Pin<Ptr>` around a reference to some data of a type that /// Constructs a new `Pin<Ptr>` around a reference to some data of a type that
/// may or may not implement [`Unpin`]. /// may or may not implement [`Unpin`].
/// ///
/// If `pointer` dereferences to an [`Unpin`] type, [`Pin::new`] should be used /// If `pointer` dereferences to an [`Unpin`] type, [`Pin::new`] should be used
@ -1569,7 +1569,7 @@ impl<'a, T: ?Sized> Pin<&'a mut T> {
self.__pointer self.__pointer
} }
/// Construct a new pin by mapping the interior value. /// Constructs a new pin by mapping the interior value.
/// ///
/// For example, if you wanted to get a `Pin` of a field of something, /// For example, if you wanted to get a `Pin` of a field of something,
/// you could use this to get access to that field in one line of code. /// you could use this to get access to that field in one line of code.
@ -1602,7 +1602,7 @@ impl<'a, T: ?Sized> Pin<&'a mut T> {
} }
impl<T: ?Sized> Pin<&'static T> { impl<T: ?Sized> Pin<&'static T> {
/// Get a pinning reference from a `&'static` reference. /// Gets a pinning reference from a `&'static` reference.
/// ///
/// This is safe because `T` is borrowed immutably for the `'static` lifetime, which /// This is safe because `T` is borrowed immutably for the `'static` lifetime, which
/// never ends. /// never ends.
@ -1639,8 +1639,8 @@ impl<'a, Ptr: DerefMut> Pin<&'a mut Pin<Ptr>> {
// //
// We need to ensure that two things hold for that to be the case: // We need to ensure that two things hold for that to be the case:
// //
// 1) Once we give out a `Pin<&mut Ptr::Target>`, an `&mut Ptr::Target` will not be given out. // 1) Once we give out a `Pin<&mut Ptr::Target>`, a `&mut Ptr::Target` will not be given out.
// 2) By giving out a `Pin<&mut Ptr::Target>`, we do not risk of violating // 2) By giving out a `Pin<&mut Ptr::Target>`, we do not risk violating
// `Pin<&mut Pin<Ptr>>` // `Pin<&mut Pin<Ptr>>`
// //
// The existence of `Pin<Ptr>` is sufficient to guarantee #1: since we already have a // The existence of `Pin<Ptr>` is sufficient to guarantee #1: since we already have a
@ -1656,7 +1656,7 @@ impl<'a, Ptr: DerefMut> Pin<&'a mut Pin<Ptr>> {
} }
impl<T: ?Sized> Pin<&'static mut T> { impl<T: ?Sized> Pin<&'static mut T> {
/// Get a pinning mutable reference from a static mutable reference. /// Gets a pinning mutable reference from a static mutable reference.
/// ///
/// This is safe because `T` is borrowed for the `'static` lifetime, which /// This is safe because `T` is borrowed for the `'static` lifetime, which
/// never ends. /// never ends.

2
library/core/src/ptr/const_ptr.rs
View File

@ -61,7 +61,7 @@ impl<T: ?Sized> *const T {
self as _ self as _
} }
/// Use the pointer value in a new pointer of another type. /// Uses the pointer value in a new pointer of another type.
/// ///
/// In case `meta` is a (fat) pointer to an unsized type, this operation /// In case `meta` is a (fat) pointer to an unsized type, this operation
/// will ignore the pointer part, whereas for (thin) pointers to sized /// will ignore the pointer part, whereas for (thin) pointers to sized

2
library/core/src/ptr/metadata.rs
View File

@ -81,7 +81,7 @@ pub trait Pointee {
// NOTE: don’t stabilize this before trait aliases are stable in the language? // NOTE: don’t stabilize this before trait aliases are stable in the language?
pub trait Thin = Pointee<Metadata = ()>; pub trait Thin = Pointee<Metadata = ()>;
/// Extract the metadata component of a pointer. /// Extracts the metadata component of a pointer.
/// ///
/// Values of type `*mut T`, `&T`, or `&mut T` can be passed directly to this function /// Values of type `*mut T`, `&T`, or `&mut T` can be passed directly to this function
/// as they implicitly coerce to `*const T`. /// as they implicitly coerce to `*const T`.

34
library/core/src/ptr/mod.rs
View File

@ -196,9 +196,9 @@
//! * The **provenance** it has, defining the memory it has permission to access. //! * The **provenance** it has, defining the memory it has permission to access.
//! Provenance can be absent, in which case the pointer does not have permission to access any memory. //! Provenance can be absent, in which case the pointer does not have permission to access any memory.
//! //!
//! Under Strict Provenance, a usize *cannot* accurately represent a pointer, and converting from //! Under Strict Provenance, a `usize` *cannot* accurately represent a pointer, and converting from
//! a pointer to a usize is generally an operation which *only* extracts the address. It is //! a pointer to a `usize` is generally an operation which *only* extracts the address. It is
//! therefore *impossible* to construct a valid pointer from a usize because there is no way //! therefore *impossible* to construct a valid pointer from a `usize` because there is no way
//! to restore the address-space and provenance. In other words, pointer-integer-pointer //! to restore the address-space and provenance. In other words, pointer-integer-pointer
//! roundtrips are not possible (in the sense that the resulting pointer is not dereferenceable). //! roundtrips are not possible (in the sense that the resulting pointer is not dereferenceable).
//! //!
@ -234,16 +234,16 @@
//! //!
//! Most code needs no changes to conform to strict provenance, as the only really concerning //! Most code needs no changes to conform to strict provenance, as the only really concerning
//! operation that *wasn't* obviously already Undefined Behaviour is casts from usize to a //! operation that *wasn't* obviously already Undefined Behaviour is casts from usize to a
//! pointer. For code which *does* cast a usize to a pointer, the scope of the change depends //! pointer. For code which *does* cast a `usize` to a pointer, the scope of the change depends
//! on exactly what you're doing. //! on exactly what you're doing.
//! //!
//! In general, you just need to make sure that if you want to convert a usize address to a //! In general, you just need to make sure that if you want to convert a `usize` address to a
//! pointer and then use that pointer to read/write memory, you need to keep around a pointer //! pointer and then use that pointer to read/write memory, you need to keep around a pointer
//! that has sufficient provenance to perform that read/write itself. In this way all of your //! that has sufficient provenance to perform that read/write itself. In this way all of your
//! casts from an address to a pointer are essentially just applying offsets/indexing. //! casts from an address to a pointer are essentially just applying offsets/indexing.
//! //!
//! This is generally trivial to do for simple cases like tagged pointers *as long as you //! This is generally trivial to do for simple cases like tagged pointers *as long as you
//! represent the tagged pointer as an actual pointer and not a usize*. For instance: //! represent the tagged pointer as an actual pointer and not a `usize`*. For instance:
//! //!
//! ``` //! ```
//! #![feature(strict_provenance)] //! #![feature(strict_provenance)]
@ -606,7 +606,7 @@ pub const fn null_mut<T: ?Sized + Thin>() -> *mut T {
/// Without provenance, this pointer is not associated with any actual allocation. Such a /// Without provenance, this pointer is not associated with any actual allocation. Such a
/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but /// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but
/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are /// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are
/// little more than a usize address in disguise. /// little more than a `usize` address in disguise.
/// ///
/// This is different from `addr as *const T`, which creates a pointer that picks up a previously /// This is different from `addr as *const T`, which creates a pointer that picks up a previously
/// exposed provenance. See [`with_exposed_provenance`] for more details on that operation. /// exposed provenance. See [`with_exposed_provenance`] for more details on that operation.
@ -650,7 +650,7 @@ pub const fn dangling<T>() -> *const T {
/// Without provenance, this pointer is not associated with any actual allocation. Such a /// Without provenance, this pointer is not associated with any actual allocation. Such a
/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but /// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but
/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are /// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are
/// little more than a usize address in disguise. /// little more than a `usize` address in disguise.
/// ///
/// This is different from `addr as *mut T`, which creates a pointer that picks up a previously /// This is different from `addr as *mut T`, which creates a pointer that picks up a previously
/// exposed provenance. See [`with_exposed_provenance_mut`] for more details on that operation. /// exposed provenance. See [`with_exposed_provenance_mut`] for more details on that operation.
@ -687,7 +687,7 @@ pub const fn dangling_mut<T>() -> *mut T {
without_provenance_mut(mem::align_of::<T>()) without_provenance_mut(mem::align_of::<T>())
} }
/// Convert an address back to a pointer, picking up a previously 'exposed' provenance. /// Converts an address back to a pointer, picking up a previously 'exposed' provenance.
/// ///
/// This is a more rigorously specified alternative to `addr as *const T`. The provenance of the /// This is a more rigorously specified alternative to `addr as *const T`. The provenance of the
/// returned pointer is that of *any* pointer that was previously exposed by passing it to /// returned pointer is that of *any* pointer that was previously exposed by passing it to
@ -735,7 +735,7 @@ where
addr as *const T addr as *const T
} }
/// Convert an address back to a mutable pointer, picking up a previously 'exposed' provenance. /// Converts an address back to a mutable pointer, picking up a previously 'exposed' provenance.
/// ///
/// This is a more rigorously specified alternative to `addr as *mut T`. The provenance of the /// This is a more rigorously specified alternative to `addr as *mut T`. The provenance of the
/// returned pointer is that of *any* pointer that was previously passed to /// returned pointer is that of *any* pointer that was previously passed to
@ -775,7 +775,7 @@ where
addr as *mut T addr as *mut T
} }
/// Convert a reference to a raw pointer. /// Converts a reference to a raw pointer.
/// ///
/// This is equivalent to `r as *const T`, but is a bit safer since it will never silently change /// This is equivalent to `r as *const T`, but is a bit safer since it will never silently change
/// type or mutability, in particular if the code is refactored. /// type or mutability, in particular if the code is refactored.
@ -789,7 +789,7 @@ pub const fn from_ref<T: ?Sized>(r: &T) -> *const T {
r r
} }
/// Convert a mutable reference to a raw pointer. /// Converts a mutable reference to a raw pointer.
/// ///
/// This is equivalent to `r as *mut T`, but is a bit safer since it will never silently change /// This is equivalent to `r as *mut T`, but is a bit safer since it will never silently change
/// type or mutability, in particular if the code is refactored. /// type or mutability, in particular if the code is refactored.
@ -1388,7 +1388,7 @@ pub const unsafe fn read<T>(src: *const T) -> T {
/// ///
/// # Examples /// # Examples
/// ///
/// Read a usize value from a byte buffer: /// Read a `usize` value from a byte buffer:
/// ///
/// ``` /// ```
/// use std::mem; /// use std::mem;
@ -1599,7 +1599,7 @@ pub const unsafe fn write<T>(dst: *mut T, src: T) {
/// ///
/// # Examples /// # Examples
/// ///
/// Write a usize value to a byte buffer: /// Write a `usize` value to a byte buffer:
/// ///
/// ``` /// ```
/// use std::mem; /// use std::mem;
@ -1934,7 +1934,7 @@ pub(crate) const unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usiz
let y = cttz_nonzero(a); let y = cttz_nonzero(a);
if x < y { x } else { y } if x < y { x } else { y }
}; };
// SAFETY: gcdpow has an upper-bound that’s at most the number of bits in a usize. // SAFETY: gcdpow has an upper-bound that’s at most the number of bits in a `usize`.
let gcd = unsafe { unchecked_shl(1usize, gcdpow) }; let gcd = unsafe { unchecked_shl(1usize, gcdpow) };
// SAFETY: gcd is always greater or equal to 1. // SAFETY: gcd is always greater or equal to 1.
if addr & unsafe { unchecked_sub(gcd, 1) } == 0 { if addr & unsafe { unchecked_sub(gcd, 1) } == 0 {
@ -2133,7 +2133,7 @@ impl<F: FnPtr> fmt::Debug for F {
} }
} }
/// Create a `const` raw pointer to a place, without creating an intermediate reference. /// Creates a `const` raw pointer to a place, without creating an intermediate reference.
/// ///
/// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned /// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned
/// and points to initialized data. For cases where those requirements do not hold, /// and points to initialized data. For cases where those requirements do not hold,
@ -2207,7 +2207,7 @@ pub macro addr_of($place:expr) {
&raw const $place &raw const $place
} }
/// Create a `mut` raw pointer to a place, without creating an intermediate reference. /// Creates a `mut` raw pointer to a place, without creating an intermediate reference.
/// ///
/// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned /// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned
/// and points to initialized data. For cases where those requirements do not hold, /// and points to initialized data. For cases where those requirements do not hold,

2
library/core/src/ptr/mut_ptr.rs
View File

@ -60,7 +60,7 @@ impl<T: ?Sized> *mut T {
self as _ self as _
} }
/// Use the pointer value in a new pointer of another type. /// Uses the pointer value in a new pointer of another type.
/// ///
/// In case `meta` is a (fat) pointer to an unsized type, this operation /// In case `meta` is a (fat) pointer to an unsized type, this operation
/// will ignore the pointer part, whereas for (thin) pointers to sized /// will ignore the pointer part, whereas for (thin) pointers to sized

6
library/core/src/range.rs
View File

@ -72,7 +72,7 @@ impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
} }
impl<Idx: Step> Range<Idx> { impl<Idx: Step> Range<Idx> {
/// Create an iterator over the elements within this range. /// Creates an iterator over the elements within this range.
/// ///
/// Shorthand for `.clone().into_iter()` /// Shorthand for `.clone().into_iter()`
/// ///
@ -292,7 +292,7 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
} }
impl<Idx: Step> RangeInclusive<Idx> { impl<Idx: Step> RangeInclusive<Idx> {
/// Create an iterator over the elements within this range. /// Creates an iterator over the elements within this range.
/// ///
/// Shorthand for `.clone().into_iter()` /// Shorthand for `.clone().into_iter()`
/// ///
@ -408,7 +408,7 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
} }
impl<Idx: Step> RangeFrom<Idx> { impl<Idx: Step> RangeFrom<Idx> {
/// Create an iterator over the elements within this range. /// Creates an iterator over the elements within this range.
/// ///
/// Shorthand for `.clone().into_iter()` /// Shorthand for `.clone().into_iter()`
/// ///

15
library/core/src/slice/index.rs
View File

@ -214,6 +214,7 @@ pub unsafe trait SliceIndex<T: ?Sized>: private_slice_index::Sealed {
/// Returns a pointer to the output at this location, without /// Returns a pointer to the output at this location, without
/// performing any bounds checking. /// performing any bounds checking.
///
/// Calling this method with an out-of-bounds index or a dangling `slice` pointer /// Calling this method with an out-of-bounds index or a dangling `slice` pointer
/// is *[undefined behavior]* even if the resulting pointer is not used. /// is *[undefined behavior]* even if the resulting pointer is not used.
/// ///
@ -223,6 +224,7 @@ pub unsafe trait SliceIndex<T: ?Sized>: private_slice_index::Sealed {
/// Returns a mutable pointer to the output at this location, without /// Returns a mutable pointer to the output at this location, without
/// performing any bounds checking. /// performing any bounds checking.
///
/// Calling this method with an out-of-bounds index or a dangling `slice` pointer /// Calling this method with an out-of-bounds index or a dangling `slice` pointer
/// is *[undefined behavior]* even if the resulting pointer is not used. /// is *[undefined behavior]* even if the resulting pointer is not used.
/// ///
@ -802,13 +804,13 @@ unsafe impl<T> SliceIndex<[T]> for ops::RangeToInclusive<usize> {
} }
} }
/// Performs bounds-checking of a range. /// Performs bounds checking of a range.
/// ///
/// This method is similar to [`Index::index`] for slices, but it returns a /// This method is similar to [`Index::index`] for slices, but it returns a
/// [`Range`] equivalent to `range`. You can use this method to turn any range /// [`Range`] equivalent to `range`. You can use this method to turn any range
/// into `start` and `end` values. /// into `start` and `end` values.
/// ///
/// `bounds` is the range of the slice to use for bounds-checking. It should /// `bounds` is the range of the slice to use for bounds checking. It should
/// be a [`RangeTo`] range that ends at the length of the slice. /// be a [`RangeTo`] range that ends at the length of the slice.
/// ///
/// The returned [`Range`] is safe to pass to [`slice::get_unchecked`] and /// The returned [`Range`] is safe to pass to [`slice::get_unchecked`] and
@ -898,7 +900,7 @@ where
ops::Range { start, end } ops::Range { start, end }
} }
/// Performs bounds-checking of a range without panicking. /// Performs bounds checking of a range without panicking.
/// ///
/// This is a version of [`range()`] that returns [`None`] instead of panicking. /// This is a version of [`range()`] that returns [`None`] instead of panicking.
/// ///
@ -951,7 +953,8 @@ where
if start > end || end > len { None } else { Some(ops::Range { start, end }) } if start > end || end > len { None } else { Some(ops::Range { start, end }) }
} }
/// Convert pair of `ops::Bound`s into `ops::Range` without performing any bounds checking and (in debug) overflow checking /// Converts a pair of `ops::Bound`s into `ops::Range` without performing any
/// bounds checking or (in debug) overflow checking.
pub(crate) fn into_range_unchecked( pub(crate) fn into_range_unchecked(
len: usize, len: usize,
(start, end): (ops::Bound<usize>, ops::Bound<usize>), (start, end): (ops::Bound<usize>, ops::Bound<usize>),
@ -970,7 +973,7 @@ pub(crate) fn into_range_unchecked(
start..end start..end
} }
/// Convert pair of `ops::Bound`s into `ops::Range`. /// Converts pair of `ops::Bound`s into `ops::Range`.
/// Returns `None` on overflowing indices. /// Returns `None` on overflowing indices.
pub(crate) fn into_range( pub(crate) fn into_range(
len: usize, len: usize,
@ -995,7 +998,7 @@ pub(crate) fn into_range(
Some(start..end) Some(start..end)
} }
/// Convert pair of `ops::Bound`s into `ops::Range`. /// Converts pair of `ops::Bound`s into `ops::Range`.
/// Panics on overflowing indices. /// Panics on overflowing indices.
pub(crate) fn into_slice_range( pub(crate) fn into_slice_range(
len: usize, len: usize,

46
library/core/src/slice/mod.rs
View File

@ -321,7 +321,7 @@ impl<T> [T] {
if let [.., last] = self { Some(last) } else { None } if let [.., last] = self { Some(last) } else { None }
} }
/// Return an array reference to the first `N` items in the slice. /// Returns an array reference to the first `N` items in the slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
/// ///
@ -350,7 +350,7 @@ impl<T> [T] {
} }
} }
/// Return a mutable array reference to the first `N` items in the slice. /// Returns a mutable array reference to the first `N` items in the slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
/// ///
@ -381,7 +381,7 @@ impl<T> [T] {
} }
} }
/// Return an array reference to the first `N` items in the slice and the remaining slice. /// Returns an array reference to the first `N` items in the slice and the remaining slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
/// ///
@ -413,7 +413,7 @@ impl<T> [T] {
} }
} }
/// Return a mutable array reference to the first `N` items in the slice and the remaining /// Returns a mutable array reference to the first `N` items in the slice and the remaining
/// slice. /// slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
@ -451,7 +451,7 @@ impl<T> [T] {
} }
} }
/// Return an array reference to the last `N` items in the slice and the remaining slice. /// Returns an array reference to the last `N` items in the slice and the remaining slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
/// ///
@ -483,7 +483,7 @@ impl<T> [T] {
} }
} }
/// Return a mutable array reference to the last `N` items in the slice and the remaining /// Returns a mutable array reference to the last `N` items in the slice and the remaining
/// slice. /// slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
@ -521,7 +521,7 @@ impl<T> [T] {
} }
} }
/// Return an array reference to the last `N` items in the slice. /// Returns an array reference to the last `N` items in the slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
/// ///
@ -554,7 +554,7 @@ impl<T> [T] {
} }
} }
/// Return a mutable array reference to the last `N` items in the slice. /// Returns a mutable array reference to the last `N` items in the slice.
/// ///
/// If the slice is not at least `N` in length, this will return `None`. /// If the slice is not at least `N` in length, this will return `None`.
/// ///
@ -828,7 +828,7 @@ impl<T> [T] {
// - Both pointers are part of the same object, as pointing directly // - Both pointers are part of the same object, as pointing directly
// past the object also counts. // past the object also counts.
// //
// - The size of the slice is never larger than isize::MAX bytes, as // - The size of the slice is never larger than `isize::MAX` bytes, as
// noted here: // noted here:
// - https://github.com/rust-lang/unsafe-code-guidelines/issues/102#issuecomment-473340447 // - https://github.com/rust-lang/unsafe-code-guidelines/issues/102#issuecomment-473340447
// - https://doc.rust-lang.org/reference/behavior-considered-undefined.html // - https://doc.rust-lang.org/reference/behavior-considered-undefined.html
@ -839,7 +839,7 @@ impl<T> [T] {
// - There is no wrapping around involved, as slices do not wrap past // - There is no wrapping around involved, as slices do not wrap past
// the end of the address space. // the end of the address space.
// //
// See the documentation of pointer::add. // See the documentation of [`pointer::add`].
let end = unsafe { start.add(self.len()) }; let end = unsafe { start.add(self.len()) };
start..end start..end
} }
@ -3021,7 +3021,7 @@ impl<T> [T] {
sort::unstable::sort(self, &mut |a, b| f(a).lt(&f(b))); sort::unstable::sort(self, &mut |a, b| f(a).lt(&f(b)));
} }
/// Reorder the slice such that the element at `index` after the reordering is at its final /// Reorders the slice such that the element at `index` after the reordering is at its final
/// sorted position. /// sorted position.
/// ///
/// This reordering has the additional property that any value at position `i < index` will be /// This reordering has the additional property that any value at position `i < index` will be
@ -3082,7 +3082,7 @@ impl<T> [T] {
sort::select::partition_at_index(self, index, T::lt) sort::select::partition_at_index(self, index, T::lt)
} }
/// Reorder the slice with a comparator function such that the element at `index` after the /// Reorders the slice with a comparator function such that the element at `index` after the
/// reordering is at its final sorted position. /// reordering is at its final sorted position.
/// ///
/// This reordering has the additional property that any value at position `i < index` will be /// This reordering has the additional property that any value at position `i < index` will be
@ -3147,7 +3147,7 @@ impl<T> [T] {
sort::select::partition_at_index(self, index, |a: &T, b: &T| compare(a, b) == Less) sort::select::partition_at_index(self, index, |a: &T, b: &T| compare(a, b) == Less)
} }
/// Reorder the slice with a key extraction function such that the element at `index` after the /// Reorders the slice with a key extraction function such that the element at `index` after the
/// reordering is at its final sorted position. /// reordering is at its final sorted position.
/// ///
/// This reordering has the additional property that any value at position `i < index` will be /// This reordering has the additional property that any value at position `i < index` will be
@ -3405,8 +3405,10 @@ impl<T> [T] {
/// Rotates the slice in-place such that the first `mid` elements of the /// Rotates the slice in-place such that the first `mid` elements of the
/// slice move to the end while the last `self.len() - mid` elements move to /// slice move to the end while the last `self.len() - mid` elements move to
/// the front. After calling `rotate_left`, the element previously at index /// the front.
/// `mid` will become the first element in the slice. ///
/// After calling `rotate_left`, the element previously at index `mid` will
/// become the first element in the slice.
/// ///
/// # Panics /// # Panics
/// ///
@ -3448,8 +3450,10 @@ impl<T> [T] {
/// Rotates the slice in-place such that the first `self.len() - k` /// Rotates the slice in-place such that the first `self.len() - k`
/// elements of the slice move to the end while the last `k` elements move /// elements of the slice move to the end while the last `k` elements move
/// to the front. After calling `rotate_right`, the element previously at /// to the front.
/// index `self.len() - k` will become the first element in the slice. ///
/// After calling `rotate_right`, the element previously at index `self.len()
/// - k` will become the first element in the slice.
/// ///
/// # Panics /// # Panics
/// ///
@ -3819,7 +3823,7 @@ impl<T> [T] {
(us_len, ts_len) (us_len, ts_len)
} }
/// Transmute the slice to a slice of another type, ensuring alignment of the types is /// Transmutes the slice to a slice of another type, ensuring alignment of the types is
/// maintained. /// maintained.
/// ///
/// This method splits the slice into three distinct slices: prefix, correctly aligned middle /// This method splits the slice into three distinct slices: prefix, correctly aligned middle
@ -3884,7 +3888,7 @@ impl<T> [T] {
} }
} }
/// Transmute the mutable slice to a mutable slice of another type, ensuring alignment of the /// Transmutes the mutable slice to a mutable slice of another type, ensuring alignment of the
/// types is maintained. /// types is maintained.
/// ///
/// This method splits the slice into three distinct slices: prefix, correctly aligned middle /// This method splits the slice into three distinct slices: prefix, correctly aligned middle
@ -3957,7 +3961,7 @@ impl<T> [T] {
} }
} }
/// Split a slice into a prefix, a middle of aligned SIMD types, and a suffix. /// Splits a slice into a prefix, a middle of aligned SIMD types, and a suffix.
/// ///
/// This is a safe wrapper around [`slice::align_to`], so inherits the same /// This is a safe wrapper around [`slice::align_to`], so inherits the same
/// guarantees as that method. /// guarantees as that method.
@ -4021,7 +4025,7 @@ impl<T> [T] {
unsafe { self.align_to() } unsafe { self.align_to() }
} }
/// Split a mutable slice into a mutable prefix, a middle of aligned SIMD types, /// Splits a mutable slice into a mutable prefix, a middle of aligned SIMD types,
/// and a mutable suffix. /// and a mutable suffix.
/// ///
/// This is a safe wrapper around [`slice::align_to_mut`], so inherits the same /// This is a safe wrapper around [`slice::align_to_mut`], so inherits the same

2
library/core/src/slice/sort/select.rs
View File

@ -12,7 +12,7 @@ use crate::slice::sort::shared::pivot::choose_pivot;
use crate::slice::sort::shared::smallsort::insertion_sort_shift_left; use crate::slice::sort::shared::smallsort::insertion_sort_shift_left;
use crate::slice::sort::unstable::quicksort::partition; use crate::slice::sort::unstable::quicksort::partition;
/// Reorder the slice such that the element at `index` is at its final sorted position. /// Reorders the slice such that the element at `index` is at its final sorted position.
pub(crate) fn partition_at_index<T, F>( pub(crate) fn partition_at_index<T, F>(
v: &mut [T], v: &mut [T],
index: usize, index: usize,

2
library/core/src/slice/sort/stable/drift.rs
View File

@ -273,7 +273,7 @@ fn stable_quicksort<T, F: FnMut(&T, &T) -> bool>(
} }
/// Compactly stores the length of a run, and whether or not it is sorted. This /// Compactly stores the length of a run, and whether or not it is sorted. This
/// can always fit in a usize because the maximum slice length is isize::MAX. /// can always fit in a `usize` because the maximum slice length is [`isize::MAX`].
#[derive(Copy, Clone)] #[derive(Copy, Clone)]
struct DriftsortRun(usize); struct DriftsortRun(usize);

4
library/core/src/slice/sort/stable/quicksort.rs
View File

@ -196,7 +196,8 @@ struct PartitionState<T> {
impl<T> PartitionState<T> { impl<T> PartitionState<T> {
/// # Safety /// # Safety
/// scan and scratch must point to valid disjoint buffers of length len. The ///
/// `scan` and `scratch` must point to valid disjoint buffers of length `len`. The
/// scan buffer must be initialized. /// scan buffer must be initialized.
unsafe fn new(scan: *const T, scratch: *mut T, len: usize) -> Self { unsafe fn new(scan: *const T, scratch: *mut T, len: usize) -> Self {
// SAFETY: See function safety comment. // SAFETY: See function safety comment.
@ -208,6 +209,7 @@ impl<T> PartitionState<T> {
/// branchless core of the partition. /// branchless core of the partition.
/// ///
/// # Safety /// # Safety
///
/// This function may be called at most `len` times. If it is called exactly /// This function may be called at most `len` times. If it is called exactly
/// `len` times the scratch buffer then contains a copy of each element from /// `len` times the scratch buffer then contains a copy of each element from
/// the scan buffer exactly once - a permutation, and num_left <= len. /// the scan buffer exactly once - a permutation, and num_left <= len.

4
library/core/src/str/converts.rs
View File

@ -206,7 +206,7 @@ pub const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
unsafe { &mut *(v as *mut [u8] as *mut str) } unsafe { &mut *(v as *mut [u8] as *mut str) }
} }
/// Creates an `&str` from a pointer and a length. /// Creates a `&str` from a pointer and a length.
/// ///
/// The pointed-to bytes must be valid UTF-8. /// The pointed-to bytes must be valid UTF-8.
/// If this might not be the case, use `str::from_utf8(slice::from_raw_parts(ptr, len))`, /// If this might not be the case, use `str::from_utf8(slice::from_raw_parts(ptr, len))`,
@ -225,7 +225,7 @@ pub const unsafe fn from_raw_parts<'a>(ptr: *const u8, len: usize) -> &'a str {
unsafe { &*ptr::from_raw_parts(ptr, len) } unsafe { &*ptr::from_raw_parts(ptr, len) }
} }
/// Creates an `&mut str` from a pointer and a length. /// Creates a `&mut str` from a pointer and a length.
/// ///
/// The pointed-to bytes must be valid UTF-8. /// The pointed-to bytes must be valid UTF-8.
/// If this might not be the case, use `str::from_utf8_mut(slice::from_raw_parts_mut(ptr, len))`, /// If this might not be the case, use `str::from_utf8_mut(slice::from_raw_parts_mut(ptr, len))`,

66
library/core/src/str/mod.rs
View File

@ -592,6 +592,7 @@ impl str {
/// Creates a string slice from another string slice, bypassing safety /// Creates a string slice from another string slice, bypassing safety
/// checks. /// checks.
///
/// This is generally not recommended, use with caution! For a safe /// This is generally not recommended, use with caution! For a safe
/// alternative see [`str`] and [`IndexMut`]. /// alternative see [`str`] and [`IndexMut`].
/// ///
@ -623,7 +624,7 @@ impl str {
unsafe { &mut *(begin..end).get_unchecked_mut(self) } unsafe { &mut *(begin..end).get_unchecked_mut(self) }
} }
/// Divide one string slice into two at an index. /// Divides one string slice into two at an index.
/// ///
/// The argument, `mid`, should be a byte offset from the start of the /// The argument, `mid`, should be a byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point. /// string. It must also be on the boundary of a UTF-8 code point.
@ -662,7 +663,7 @@ impl str {
} }
} }
/// Divide one mutable string slice into two at an index. /// Divides one mutable string slice into two at an index.
/// ///
/// The argument, `mid`, should be a byte offset from the start of the /// The argument, `mid`, should be a byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point. /// string. It must also be on the boundary of a UTF-8 code point.
@ -705,7 +706,7 @@ impl str {
} }
} }
/// Divide one string slice into two at an index. /// Divides one string slice into two at an index.
/// ///
/// The argument, `mid`, should be a valid byte offset from the start of the /// The argument, `mid`, should be a valid byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point. The /// string. It must also be on the boundary of a UTF-8 code point. The
@ -744,7 +745,7 @@ impl str {
} }
} }
/// Divide one mutable string slice into two at an index. /// Divides one mutable string slice into two at an index.
/// ///
/// The argument, `mid`, should be a valid byte offset from the start of the /// The argument, `mid`, should be a valid byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point. The /// string. It must also be on the boundary of a UTF-8 code point. The
@ -784,7 +785,7 @@ impl str {
} }
} }
/// Divide one string slice into two at an index. /// Divides one string slice into two at an index.
/// ///
/// # Safety /// # Safety
/// ///
@ -912,7 +913,7 @@ impl str {
CharIndices { front_offset: 0, iter: self.chars() } CharIndices { front_offset: 0, iter: self.chars() }
} }
/// An iterator over the bytes of a string slice. /// Returns an iterator over the bytes of a string slice.
/// ///
/// As a string slice consists of a sequence of bytes, we can iterate /// As a string slice consists of a sequence of bytes, we can iterate
/// through a string slice by byte. This method returns such an iterator. /// through a string slice by byte. This method returns such an iterator.
@ -1038,7 +1039,7 @@ impl str {
SplitAsciiWhitespace { inner } SplitAsciiWhitespace { inner }
} }
/// An iterator over the lines of a string, as string slices. /// Returns an iterator over the lines of a string, as string slices.
/// ///
/// Lines are split at line endings that are either newlines (`\n`) or /// Lines are split at line endings that are either newlines (`\n`) or
/// sequences of a carriage return followed by a line feed (`\r\n`). /// sequences of a carriage return followed by a line feed (`\r\n`).
@ -1089,7 +1090,7 @@ impl str {
Lines(self.split_inclusive('\n').map(LinesMap)) Lines(self.split_inclusive('\n').map(LinesMap))
} }
/// An iterator over the lines of a string. /// Returns an iterator over the lines of a string.
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[deprecated(since = "1.4.0", note = "use lines() instead now", suggestion = "lines")] #[deprecated(since = "1.4.0", note = "use lines() instead now", suggestion = "lines")]
#[inline] #[inline]
@ -1303,7 +1304,7 @@ impl str {
pat.into_searcher(self).next_match_back().map(|(i, _)| i) pat.into_searcher(self).next_match_back().map(|(i, _)| i)
} }
/// An iterator over substrings of this string slice, separated by /// Returns an iterator over substrings of this string slice, separated by
/// characters matched by a pattern. /// characters matched by a pattern.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
@ -1428,10 +1429,11 @@ impl str {
}) })
} }
/// An iterator over substrings of this string slice, separated by /// Returns an iterator over substrings of this string slice, separated by
/// characters matched by a pattern. Differs from the iterator produced by /// characters matched by a pattern.
/// `split` in that `split_inclusive` leaves the matched part as the ///
/// terminator of the substring. /// Differs from the iterator produced by `split` in that `split_inclusive`
/// leaves the matched part as the terminator of the substring.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches. /// function or closure that determines if a character matches.
@ -1468,8 +1470,8 @@ impl str {
}) })
} }
/// An iterator over substrings of the given string slice, separated by /// Returns an iterator over substrings of the given string slice, separated
/// characters matched by a pattern and yielded in reverse order. /// by characters matched by a pattern and yielded in reverse order.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches. /// function or closure that determines if a character matches.
@ -1520,8 +1522,8 @@ impl str {
RSplit(self.split(pat).0) RSplit(self.split(pat).0)
} }
/// An iterator over substrings of the given string slice, separated by /// Returns an iterator over substrings of the given string slice, separated
/// characters matched by a pattern. /// by characters matched by a pattern.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches. /// function or closure that determines if a character matches.
@ -1566,7 +1568,7 @@ impl str {
SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 }) SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
} }
/// An iterator over substrings of `self`, separated by characters /// Returns an iterator over substrings of `self`, separated by characters
/// matched by a pattern and yielded in reverse order. /// matched by a pattern and yielded in reverse order.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
@ -1615,8 +1617,8 @@ impl str {
RSplitTerminator(self.split_terminator(pat).0) RSplitTerminator(self.split_terminator(pat).0)
} }
/// An iterator over substrings of the given string slice, separated by a /// Returns an iterator over substrings of the given string slice, separated
/// pattern, restricted to returning at most `n` items. /// by a pattern, restricted to returning at most `n` items.
/// ///
/// If `n` substrings are returned, the last substring (the `n`th substring) /// If `n` substrings are returned, the last substring (the `n`th substring)
/// will contain the remainder of the string. /// will contain the remainder of the string.
@ -1667,9 +1669,9 @@ impl str {
SplitN(SplitNInternal { iter: self.split(pat).0, count: n }) SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
} }
/// An iterator over substrings of this string slice, separated by a /// Returns an iterator over substrings of this string slice, separated by a
/// pattern, starting from the end of the string, restricted to returning /// pattern, starting from the end of the string, restricted to returning at
/// at most `n` items. /// most `n` items.
/// ///
/// If `n` substrings are returned, the last substring (the `n`th substring) /// If `n` substrings are returned, the last substring (the `n`th substring)
/// will contain the remainder of the string. /// will contain the remainder of the string.
@ -1759,8 +1761,8 @@ impl str {
unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) } unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
} }
/// An iterator over the disjoint matches of a pattern within the given string /// Returns an iterator over the disjoint matches of a pattern within the
/// slice. /// given string slice.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches. /// function or closure that determines if a character matches.
@ -1794,8 +1796,8 @@ impl str {
Matches(MatchesInternal(pat.into_searcher(self))) Matches(MatchesInternal(pat.into_searcher(self)))
} }
/// An iterator over the disjoint matches of a pattern within this string slice, /// Returns an iterator over the disjoint matches of a pattern within this
/// yielded in reverse order. /// string slice, yielded in reverse order.
/// ///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches. /// function or closure that determines if a character matches.
@ -1831,7 +1833,7 @@ impl str {
RMatches(self.matches(pat).0) RMatches(self.matches(pat).0)
} }
/// An iterator over the disjoint matches of a pattern within this string /// Returns an iterator over the disjoint matches of a pattern within this string
/// slice as well as the index that the match starts at. /// slice as well as the index that the match starts at.
/// ///
/// For matches of `pat` within `self` that overlap, only the indices /// For matches of `pat` within `self` that overlap, only the indices
@ -1872,7 +1874,7 @@ impl str {
MatchIndices(MatchIndicesInternal(pat.into_searcher(self))) MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
} }
/// An iterator over the disjoint matches of a pattern within `self`, /// Returns an iterator over the disjoint matches of a pattern within `self`,
/// yielded in reverse order along with the index of the match. /// yielded in reverse order along with the index of the match.
/// ///
/// For matches of `pat` within `self` that overlap, only the indices /// For matches of `pat` within `self` that overlap, only the indices
@ -2597,7 +2599,7 @@ impl str {
unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii()) } unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii()) }
} }
/// Return an iterator that escapes each char in `self` with [`char::escape_debug`]. /// Returns an iterator that escapes each char in `self` with [`char::escape_debug`].
/// ///
/// Note: only extended grapheme codepoints that begin the string will be /// Note: only extended grapheme codepoints that begin the string will be
/// escaped. /// escaped.
@ -2646,7 +2648,7 @@ impl str {
} }
} }
/// Return an iterator that escapes each char in `self` with [`char::escape_default`]. /// Returns an iterator that escapes each char in `self` with [`char::escape_default`].
/// ///
/// # Examples /// # Examples
/// ///
@ -2684,7 +2686,7 @@ impl str {
EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) } EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
} }
/// Return an iterator that escapes each char in `self` with [`char::escape_unicode`]. /// Returns an iterator that escapes each char in `self` with [`char::escape_unicode`].
/// ///
/// # Examples /// # Examples
/// ///

12
library/core/src/sync/atomic.rs
View File

@ -481,7 +481,7 @@ impl AtomicBool {
unsafe { &mut *(self.v.get() as *mut bool) } unsafe { &mut *(self.v.get() as *mut bool) }
} }
/// Get atomic access to a `&mut bool`. /// Gets atomic access to a `&mut bool`.
/// ///
/// # Examples /// # Examples
/// ///
@ -503,7 +503,7 @@ impl AtomicBool {
unsafe { &mut *(v as *mut bool as *mut Self) } unsafe { &mut *(v as *mut bool as *mut Self) }
} }
/// Get non-atomic access to a `&mut [AtomicBool]` slice. /// Gets non-atomic access to a `&mut [AtomicBool]` slice.
/// ///
/// This is safe because the mutable reference guarantees that no other threads are /// This is safe because the mutable reference guarantees that no other threads are
/// concurrently accessing the atomic data. /// concurrently accessing the atomic data.
@ -537,7 +537,7 @@ impl AtomicBool {
unsafe { &mut *(this as *mut [Self] as *mut [bool]) } unsafe { &mut *(this as *mut [Self] as *mut [bool]) }
} }
/// Get atomic access to a `&mut [bool]` slice. /// Gets atomic access to a `&mut [bool]` slice.
/// ///
/// # Examples /// # Examples
/// ///
@ -1276,7 +1276,7 @@ impl<T> AtomicPtr<T> {
self.p.get_mut() self.p.get_mut()
} }
/// Get atomic access to a pointer. /// Gets atomic access to a pointer.
/// ///
/// # Examples /// # Examples
/// ///
@ -1303,7 +1303,7 @@ impl<T> AtomicPtr<T> {
unsafe { &mut *(v as *mut *mut T as *mut Self) } unsafe { &mut *(v as *mut *mut T as *mut Self) }
} }
/// Get non-atomic access to a `&mut [AtomicPtr]` slice. /// Gets non-atomic access to a `&mut [AtomicPtr]` slice.
/// ///
/// This is safe because the mutable reference guarantees that no other threads are /// This is safe because the mutable reference guarantees that no other threads are
/// concurrently accessing the atomic data. /// concurrently accessing the atomic data.
@ -1343,7 +1343,7 @@ impl<T> AtomicPtr<T> {
unsafe { &mut *(this as *mut [Self] as *mut [*mut T]) } unsafe { &mut *(this as *mut [Self] as *mut [*mut T]) }
} }
/// Get atomic access to a slice of pointers. /// Gets atomic access to a slice of pointers.
/// ///
/// # Examples /// # Examples
/// ///

4
library/core/src/sync/exclusive.rs
View File

@ -114,7 +114,7 @@ impl<T: Sized> Exclusive<T> {
} }
impl<T: ?Sized> Exclusive<T> { impl<T: ?Sized> Exclusive<T> {
/// Get exclusive access to the underlying value. /// Gets exclusive access to the underlying value.
#[unstable(feature = "exclusive_wrapper", issue = "98407")] #[unstable(feature = "exclusive_wrapper", issue = "98407")]
#[must_use] #[must_use]
#[inline] #[inline]
@ -122,7 +122,7 @@ impl<T: ?Sized> Exclusive<T> {
&mut self.inner &mut self.inner
} }
/// Get pinned exclusive access to the underlying value. /// Gets pinned exclusive access to the underlying value.
/// ///
/// `Exclusive` is considered to _structurally pin_ the underlying /// `Exclusive` is considered to _structurally pin_ the underlying
/// value, which means _unpinned_ `Exclusive`s can produce _unpinned_ /// value, which means _unpinned_ `Exclusive`s can produce _unpinned_

33
library/core/src/task/wake.rs
View File

@ -61,7 +61,7 @@ impl RawWaker {
RawWaker { data, vtable } RawWaker { data, vtable }
} }
/// Get the `data` pointer used to create this `RawWaker`. /// Gets the `data` pointer used to create this `RawWaker`.
#[inline] #[inline]
#[must_use] #[must_use]
#[unstable(feature = "waker_getters", issue = "96992")] #[unstable(feature = "waker_getters", issue = "96992")]
@ -69,7 +69,7 @@ impl RawWaker {
self.data self.data
} }
/// Get the `vtable` pointer used to create this `RawWaker`. /// Gets the `vtable` pointer used to create this `RawWaker`.
#[inline] #[inline]
#[must_use] #[must_use]
#[unstable(feature = "waker_getters", issue = "96992")] #[unstable(feature = "waker_getters", issue = "96992")]
@ -150,7 +150,7 @@ pub struct RawWakerVTable {
/// pointer. /// pointer.
wake_by_ref: unsafe fn(*const ()), wake_by_ref: unsafe fn(*const ()),
/// This function gets called when a [`Waker`] gets dropped. /// This function will be called when a [`Waker`] gets dropped.
/// ///
/// The implementation of this function must make sure to release any /// The implementation of this function must make sure to release any
/// resources that are associated with this instance of a [`RawWaker`] and /// resources that are associated with this instance of a [`RawWaker`] and
@ -203,7 +203,8 @@ impl RawWakerVTable {
/// ///
/// # `drop` /// # `drop`
/// ///
/// This function gets called when a [`Waker`]/[`LocalWaker`] gets dropped. /// This function will be called when a [`Waker`]/[`LocalWaker`] gets
/// dropped.
/// ///
/// The implementation of this function must make sure to release any /// The implementation of this function must make sure to release any
/// resources that are associated with this instance of a [`RawWaker`] and /// resources that are associated with this instance of a [`RawWaker`] and
@ -248,7 +249,7 @@ pub struct Context<'a> {
} }
impl<'a> Context<'a> { impl<'a> Context<'a> {
/// Create a new `Context` from a [`&Waker`](Waker). /// Creates a new `Context` from a [`&Waker`](Waker).
#[stable(feature = "futures_api", since = "1.36.0")] #[stable(feature = "futures_api", since = "1.36.0")]
#[rustc_const_unstable(feature = "const_waker", issue = "102012")] #[rustc_const_unstable(feature = "const_waker", issue = "102012")]
#[must_use] #[must_use]
@ -334,7 +335,7 @@ pub struct ContextBuilder<'a> {
} }
impl<'a> ContextBuilder<'a> { impl<'a> ContextBuilder<'a> {
/// Create a ContextBuilder from a Waker. /// Creates a ContextBuilder from a Waker.
#[inline] #[inline]
#[rustc_const_unstable(feature = "const_waker", issue = "102012")] #[rustc_const_unstable(feature = "const_waker", issue = "102012")]
#[unstable(feature = "local_waker", issue = "118959")] #[unstable(feature = "local_waker", issue = "118959")]
@ -350,7 +351,7 @@ impl<'a> ContextBuilder<'a> {
} }
} }
/// Create a ContextBuilder from an existing Context. /// Creates a ContextBuilder from an existing Context.
#[inline] #[inline]
#[rustc_const_unstable(feature = "const_waker", issue = "102012")] #[rustc_const_unstable(feature = "const_waker", issue = "102012")]
#[unstable(feature = "context_ext", issue = "123392")] #[unstable(feature = "context_ext", issue = "123392")]
@ -368,7 +369,7 @@ impl<'a> ContextBuilder<'a> {
} }
} }
/// This method is used to set the value for the waker on `Context`. /// Sets the value for the waker on `Context`.
#[inline] #[inline]
#[unstable(feature = "context_ext", issue = "123392")] #[unstable(feature = "context_ext", issue = "123392")]
#[rustc_const_unstable(feature = "const_waker", issue = "102012")] #[rustc_const_unstable(feature = "const_waker", issue = "102012")]
@ -376,7 +377,7 @@ impl<'a> ContextBuilder<'a> {
Self { waker, ..self } Self { waker, ..self }
} }
/// This method is used to set the value for the local waker on `Context`. /// Sets the value for the local waker on `Context`.
#[inline] #[inline]
#[unstable(feature = "local_waker", issue = "118959")] #[unstable(feature = "local_waker", issue = "118959")]
#[rustc_const_unstable(feature = "const_waker", issue = "102012")] #[rustc_const_unstable(feature = "const_waker", issue = "102012")]
@ -384,7 +385,7 @@ impl<'a> ContextBuilder<'a> {
Self { local_waker, ..self } Self { local_waker, ..self }
} }
/// This method is used to set the value for the extension data on `Context`. /// Sets the value for the extension data on `Context`.
#[inline] #[inline]
#[unstable(feature = "context_ext", issue = "123392")] #[unstable(feature = "context_ext", issue = "123392")]
#[rustc_const_unstable(feature = "const_waker", issue = "102012")] #[rustc_const_unstable(feature = "const_waker", issue = "102012")]
@ -442,7 +443,7 @@ unsafe impl Send for Waker {}
unsafe impl Sync for Waker {} unsafe impl Sync for Waker {}
impl Waker { impl Waker {
/// Wake up the task associated with this `Waker`. /// Wakes up the task associated with this `Waker`.
/// ///
/// As long as the executor keeps running and the task is not finished, it is /// As long as the executor keeps running and the task is not finished, it is
/// guaranteed that each invocation of [`wake()`](Self::wake) (or /// guaranteed that each invocation of [`wake()`](Self::wake) (or
@ -474,7 +475,7 @@ impl Waker {
unsafe { (this.waker.vtable.wake)(this.waker.data) }; unsafe { (this.waker.vtable.wake)(this.waker.data) };
} }
/// Wake up the task associated with this `Waker` without consuming the `Waker`. /// Wakes up the task associated with this `Waker` without consuming the `Waker`.
/// ///
/// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in
/// the case where an owned `Waker` is available. This method should be preferred to /// the case where an owned `Waker` is available. This method should be preferred to
@ -555,7 +556,7 @@ impl Waker {
WAKER WAKER
} }
/// Get a reference to the underlying [`RawWaker`]. /// Gets a reference to the underlying [`RawWaker`].
#[inline] #[inline]
#[must_use] #[must_use]
#[unstable(feature = "waker_getters", issue = "96992")] #[unstable(feature = "waker_getters", issue = "96992")]
@ -701,7 +702,7 @@ pub struct LocalWaker {
impl Unpin for LocalWaker {} impl Unpin for LocalWaker {}
impl LocalWaker { impl LocalWaker {
/// Wake up the task associated with this `LocalWaker`. /// Wakes up the task associated with this `LocalWaker`.
/// ///
/// As long as the executor keeps running and the task is not finished, it is /// As long as the executor keeps running and the task is not finished, it is
/// guaranteed that each invocation of [`wake()`](Self::wake) (or /// guaranteed that each invocation of [`wake()`](Self::wake) (or
@ -733,7 +734,7 @@ impl LocalWaker {
unsafe { (this.waker.vtable.wake)(this.waker.data) }; unsafe { (this.waker.vtable.wake)(this.waker.data) };
} }
/// Wake up the task associated with this `LocalWaker` without consuming the `LocalWaker`. /// Wakes up the task associated with this `LocalWaker` without consuming the `LocalWaker`.
/// ///
/// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in
/// the case where an owned `Waker` is available. This method should be preferred to /// the case where an owned `Waker` is available. This method should be preferred to
@ -807,7 +808,7 @@ impl LocalWaker {
WAKER WAKER
} }
/// Get a reference to the underlying [`RawWaker`]. /// Gets a reference to the underlying [`RawWaker`].
#[inline] #[inline]
#[must_use] #[must_use]
#[unstable(feature = "waker_getters", issue = "96992")] #[unstable(feature = "waker_getters", issue = "96992")]

8
library/core/src/time.rs
View File

@ -1037,7 +1037,7 @@ impl Duration {
Duration::from_secs_f32(rhs * self.as_secs_f32()) Duration::from_secs_f32(rhs * self.as_secs_f32())
} }
/// Divide `Duration` by `f64`. /// Divides `Duration` by `f64`.
/// ///
/// # Panics /// # Panics
/// This method will panic if result is negative, overflows `Duration` or not finite. /// This method will panic if result is negative, overflows `Duration` or not finite.
@ -1058,7 +1058,7 @@ impl Duration {
Duration::from_secs_f64(self.as_secs_f64() / rhs) Duration::from_secs_f64(self.as_secs_f64() / rhs)
} }
/// Divide `Duration` by `f32`. /// Divides `Duration` by `f32`.
/// ///
/// # Panics /// # Panics
/// This method will panic if result is negative, overflows `Duration` or not finite. /// This method will panic if result is negative, overflows `Duration` or not finite.
@ -1081,7 +1081,7 @@ impl Duration {
Duration::from_secs_f32(self.as_secs_f32() / rhs) Duration::from_secs_f32(self.as_secs_f32() / rhs)
} }
/// Divide `Duration` by `Duration` and return `f64`. /// Divides `Duration` by `Duration` and returns `f64`.
/// ///
/// # Examples /// # Examples
/// ``` /// ```
@ -1102,7 +1102,7 @@ impl Duration {
self_nanos / rhs_nanos self_nanos / rhs_nanos
} }
/// Divide `Duration` by `Duration` and return `f32`. /// Divides `Duration` by `Duration` and returns `f32`.
/// ///
/// # Examples /// # Examples
/// ``` /// ```

8
library/core/src/ub_checks.rs
View File

@ -3,9 +3,11 @@
use crate::intrinsics::{self, const_eval_select}; use crate::intrinsics::{self, const_eval_select};
/// Check that the preconditions of an unsafe function are followed. The check is enabled at /// Checks that the preconditions of an unsafe function are followed.
/// runtime if debug assertions are enabled when the caller is monomorphized. In const-eval/Miri ///
/// checks implemented with this macro for language UB are always ignored. /// The check is enabled at runtime if debug assertions are enabled when the
/// caller is monomorphized. In const-eval/Miri checks implemented with this
/// macro for language UB are always ignored.
/// ///
/// This macro should be called as /// This macro should be called as
/// `assert_unsafe_precondition!(check_{library,lang}_ub, "message", (ident: type = expr, ident: type = expr) => check_expr)` /// `assert_unsafe_precondition!(check_{library,lang}_ub, "message", (ident: type = expr, ident: type = expr) => check_expr)`

2
library/core/tests/ptr.rs
View File

@ -1050,7 +1050,7 @@ fn nonnull_tagged_pointer_with_provenance() {
/// A mask for the non-data-carrying bits of the address. /// A mask for the non-data-carrying bits of the address.
pub const ADDRESS_MASK: usize = usize::MAX << Self::NUM_BITS; pub const ADDRESS_MASK: usize = usize::MAX << Self::NUM_BITS;
/// Create a new tagged pointer from a possibly null pointer. /// Creates a new tagged pointer from a possibly null pointer.
pub fn new(pointer: *mut T) -> Option<TaggedPointer<T>> { pub fn new(pointer: *mut T) -> Option<TaggedPointer<T>> {
Some(TaggedPointer(NonNull::new(pointer)?)) Some(TaggedPointer(NonNull::new(pointer)?))
} }

12
library/portable-simd/crates/core_simd/src/masks.rs
View File

@ -137,7 +137,7 @@ where
T: MaskElement, T: MaskElement,
LaneCount<N>: SupportedLaneCount, LaneCount<N>: SupportedLaneCount,
{ {
/// Construct a mask by setting all elements to the given value. /// Constructs a mask by setting all elements to the given value.
#[inline] #[inline]
pub fn splat(value: bool) -> Self { pub fn splat(value: bool) -> Self {
Self(mask_impl::Mask::splat(value)) Self(mask_impl::Mask::splat(value))
@ -288,7 +288,7 @@ where
self.0.all() self.0.all()
} }
/// Create a bitmask from a mask. /// Creates a bitmask from a mask.
/// ///
/// Each bit is set if the corresponding element in the mask is `true`. /// Each bit is set if the corresponding element in the mask is `true`.
/// If the mask contains more than 64 elements, the bitmask is truncated to the first 64. /// If the mask contains more than 64 elements, the bitmask is truncated to the first 64.
@ -298,7 +298,7 @@ where
self.0.to_bitmask_integer() self.0.to_bitmask_integer()
} }
/// Create a mask from a bitmask. /// Creates a mask from a bitmask.
/// ///
/// For each bit, if it is set, the corresponding element in the mask is set to `true`. /// For each bit, if it is set, the corresponding element in the mask is set to `true`.
/// If the mask contains more than 64 elements, the remainder are set to `false`. /// If the mask contains more than 64 elements, the remainder are set to `false`.
@ -308,7 +308,7 @@ where
Self(mask_impl::Mask::from_bitmask_integer(bitmask)) Self(mask_impl::Mask::from_bitmask_integer(bitmask))
} }
/// Create a bitmask vector from a mask. /// Creates a bitmask vector from a mask.
/// ///
/// Each bit is set if the corresponding element in the mask is `true`. /// Each bit is set if the corresponding element in the mask is `true`.
/// The remaining bits are unset. /// The remaining bits are unset.
@ -328,7 +328,7 @@ where
self.0.to_bitmask_vector() self.0.to_bitmask_vector()
} }
/// Create a mask from a bitmask vector. /// Creates a mask from a bitmask vector.
/// ///
/// For each bit, if it is set, the corresponding element in the mask is set to `true`. /// For each bit, if it is set, the corresponding element in the mask is set to `true`.
/// ///
@ -350,7 +350,7 @@ where
Self(mask_impl::Mask::from_bitmask_vector(bitmask)) Self(mask_impl::Mask::from_bitmask_vector(bitmask))
} }
/// Find the index of the first set element. /// Finds the index of the first set element.
/// ///
/// ``` /// ```
/// # #![feature(portable_simd)] /// # #![feature(portable_simd)]

2
library/portable-simd/crates/core_simd/src/simd/ptr/const_ptr.rs
View File

@ -54,7 +54,7 @@ pub trait SimdConstPtr: Copy + Sealed {
/// [`Self::with_exposed_provenance`] and returns the "address" portion. /// [`Self::with_exposed_provenance`] and returns the "address" portion.
fn expose_provenance(self) -> Self::Usize; fn expose_provenance(self) -> Self::Usize;
/// Convert an address back to a pointer, picking up a previously "exposed" provenance. /// Converts an address back to a pointer, picking up a previously "exposed" provenance.
/// ///
/// Equivalent to calling [`core::ptr::with_exposed_provenance`] on each element. /// Equivalent to calling [`core::ptr::with_exposed_provenance`] on each element.
fn with_exposed_provenance(addr: Self::Usize) -> Self; fn with_exposed_provenance(addr: Self::Usize) -> Self;

2
library/portable-simd/crates/core_simd/src/simd/ptr/mut_ptr.rs
View File

@ -51,7 +51,7 @@ pub trait SimdMutPtr: Copy + Sealed {
/// [`Self::with_exposed_provenance`] and returns the "address" portion. /// [`Self::with_exposed_provenance`] and returns the "address" portion.
fn expose_provenance(self) -> Self::Usize; fn expose_provenance(self) -> Self::Usize;
/// Convert an address back to a pointer, picking up a previously "exposed" provenance. /// Converts an address back to a pointer, picking up a previously "exposed" provenance.
/// ///
/// Equivalent to calling [`core::ptr::with_exposed_provenance_mut`] on each element. /// Equivalent to calling [`core::ptr::with_exposed_provenance_mut`] on each element.
fn with_exposed_provenance(addr: Self::Usize) -> Self; fn with_exposed_provenance(addr: Self::Usize) -> Self;

10
library/portable-simd/crates/core_simd/src/swizzle.rs
View File

@ -69,12 +69,12 @@ pub macro simd_swizzle {
} }
} }
/// Create a vector from the elements of another vector. /// Creates a vector from the elements of another vector.
pub trait Swizzle<const N: usize> { pub trait Swizzle<const N: usize> {
/// Map from the elements of the input vector to the output vector. /// Map from the elements of the input vector to the output vector.
const INDEX: [usize; N]; const INDEX: [usize; N];
/// Create a new vector from the elements of `vector`. /// Creates a new vector from the elements of `vector`.
/// ///
/// Lane `i` of the output is `vector[Self::INDEX[i]]`. /// Lane `i` of the output is `vector[Self::INDEX[i]]`.
#[inline] #[inline]
@ -109,7 +109,7 @@ pub trait Swizzle<const N: usize> {
} }
} }
/// Create a new vector from the elements of `first` and `second`. /// Creates a new vector from the elements of `first` and `second`.
/// ///
/// Lane `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of /// Lane `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of
/// `first` and `second`. /// `first` and `second`.
@ -145,7 +145,7 @@ pub trait Swizzle<const N: usize> {
} }
} }
/// Create a new mask from the elements of `mask`. /// Creates a new mask from the elements of `mask`.
/// ///
/// Element `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of /// Element `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of
/// `first` and `second`. /// `first` and `second`.
@ -161,7 +161,7 @@ pub trait Swizzle<const N: usize> {
unsafe { Mask::from_int_unchecked(Self::swizzle(mask.to_int())) } unsafe { Mask::from_int_unchecked(Self::swizzle(mask.to_int())) }
} }
/// Create a new mask from the elements of `first` and `second`. /// Creates a new mask from the elements of `first` and `second`.
/// ///
/// Element `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of /// Element `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of
/// `first` and `second`. /// `first` and `second`.

14
library/portable-simd/crates/core_simd/src/to_bytes.rs
View File

@ -10,7 +10,7 @@ mod sealed {
} }
use sealed::Sealed; use sealed::Sealed;
/// Convert SIMD vectors to vectors of bytes /// Converts SIMD vectors to vectors of bytes
pub trait ToBytes: Sealed { pub trait ToBytes: Sealed {
/// This type, reinterpreted as bytes. /// This type, reinterpreted as bytes.
type Bytes: Copy type Bytes: Copy
@ -22,26 +22,26 @@ pub trait ToBytes: Sealed {
+ SimdUint<Scalar = u8> + SimdUint<Scalar = u8>
+ 'static; + 'static;
/// Return the memory representation of this integer as a byte array in native byte /// Returns the memory representation of this integer as a byte array in native byte
/// order. /// order.
fn to_ne_bytes(self) -> Self::Bytes; fn to_ne_bytes(self) -> Self::Bytes;
/// Return the memory representation of this integer as a byte array in big-endian /// Returns the memory representation of this integer as a byte array in big-endian
/// (network) byte order. /// (network) byte order.
fn to_be_bytes(self) -> Self::Bytes; fn to_be_bytes(self) -> Self::Bytes;
/// Return the memory representation of this integer as a byte array in little-endian /// Returns the memory representation of this integer as a byte array in little-endian
/// byte order. /// byte order.
fn to_le_bytes(self) -> Self::Bytes; fn to_le_bytes(self) -> Self::Bytes;
/// Create a native endian integer value from its memory representation as a byte array /// Creates a native endian integer value from its memory representation as a byte array
/// in native endianness. /// in native endianness.
fn from_ne_bytes(bytes: Self::Bytes) -> Self; fn from_ne_bytes(bytes: Self::Bytes) -> Self;
/// Create an integer value from its representation as a byte array in big endian. /// Creates an integer value from its representation as a byte array in big endian.
fn from_be_bytes(bytes: Self::Bytes) -> Self; fn from_be_bytes(bytes: Self::Bytes) -> Self;
/// Create an integer value from its representation as a byte array in little endian. /// Creates an integer value from its representation as a byte array in little endian.
fn from_le_bytes(bytes: Self::Bytes) -> Self; fn from_le_bytes(bytes: Self::Bytes) -> Self;
} }

6
library/portable-simd/crates/core_simd/src/vector.rs
View File

@ -187,7 +187,7 @@ where
unsafe { &mut *(self as *mut Self as *mut [T; N]) } unsafe { &mut *(self as *mut Self as *mut [T; N]) }
} }
/// Load a vector from an array of `T`. /// Loads a vector from an array of `T`.
/// ///
/// This function is necessary since `repr(simd)` has padding for non-power-of-2 vectors (at the time of writing). /// This function is necessary since `repr(simd)` has padding for non-power-of-2 vectors (at the time of writing).
/// With padding, `read_unaligned` will read past the end of an array of N elements. /// With padding, `read_unaligned` will read past the end of an array of N elements.
@ -567,7 +567,7 @@ where
unsafe { Self::gather_select_ptr(ptrs, enable, or) } unsafe { Self::gather_select_ptr(ptrs, enable, or) }
} }
/// Read elementwise from pointers into a SIMD vector. /// Reads elementwise from pointers into a SIMD vector.
/// ///
/// # Safety /// # Safety
/// ///
@ -808,7 +808,7 @@ where
} }
} }
/// Write pointers elementwise into a SIMD vector. /// Writes pointers elementwise into a SIMD vector.
/// ///
/// # Safety /// # Safety
/// ///

2
library/proc_macro/src/bridge/server.rs
View File

@ -350,7 +350,7 @@ where
/// A message pipe used for communicating between server and client threads. /// A message pipe used for communicating between server and client threads.
pub trait MessagePipe<T>: Sized { pub trait MessagePipe<T>: Sized {
/// Create a new pair of endpoints for the message pipe. /// Creates a new pair of endpoints for the message pipe.
fn new() -> (Self, Self); fn new() -> (Self, Self);
/// Send a message to the other endpoint of this pipe. /// Send a message to the other endpoint of this pipe.

6
library/proc_macro/src/bridge/symbol.rs
View File

@ -28,7 +28,7 @@ impl Symbol {
INTERNER.with_borrow_mut(|i| i.intern(string)) INTERNER.with_borrow_mut(|i| i.intern(string))
} }
/// Create a new `Symbol` for an identifier. /// Creates a new `Symbol` for an identifier.
/// ///
/// Validates and normalizes before converting it to a symbol. /// Validates and normalizes before converting it to a symbol.
pub(crate) fn new_ident(string: &str, is_raw: bool) -> Self { pub(crate) fn new_ident(string: &str, is_raw: bool) -> Self {
@ -63,7 +63,7 @@ impl Symbol {
INTERNER.with_borrow_mut(|i| i.clear()); INTERNER.with_borrow_mut(|i| i.clear());
} }
/// Check if the ident is a valid ASCII identifier. /// Checks if the ident is a valid ASCII identifier.
/// ///
/// This is a short-circuit which is cheap to implement within the /// This is a short-circuit which is cheap to implement within the
/// proc-macro client to avoid RPC when creating simple idents, but may /// proc-macro client to avoid RPC when creating simple idents, but may
@ -177,7 +177,7 @@ impl Interner {
name name
} }
/// Read a symbol's value from the store while it is held. /// Reads a symbol's value from the store while it is held.
fn get(&self, symbol: Symbol) -> &str { fn get(&self, symbol: Symbol) -> &str {
// NOTE: Subtract out the offset which was added to make the symbol // NOTE: Subtract out the offset which was added to make the symbol
// nonzero and prevent symbol name re-use. // nonzero and prevent symbol name re-use.

2
library/std/src/backtrace.rs
View File

@ -271,7 +271,7 @@ impl Backtrace {
enabled enabled
} }
/// Capture a stack backtrace of the current thread. /// Captures a stack backtrace of the current thread.
/// ///
/// This function will capture a stack backtrace of the current OS thread of /// This function will capture a stack backtrace of the current OS thread of
/// execution, returning a `Backtrace` type which can be later used to print /// execution, returning a `Backtrace` type which can be later used to print

2
library/std/src/error.rs
View File

@ -234,7 +234,7 @@ impl<E> Report<E>
where where
Report<E>: From<E>, Report<E>: From<E>,
{ {
/// Create a new `Report` from an input error. /// Creates a new `Report` from an input error.
#[unstable(feature = "error_reporter", issue = "90172")] #[unstable(feature = "error_reporter", issue = "90172")]
pub fn new(error: E) -> Report<E> { pub fn new(error: E) -> Report<E> {
Self::from(error) Self::from(error)

20
library/std/src/fs.rs
View File

@ -50,7 +50,7 @@ use crate::time::SystemTime;
/// } /// }
/// ``` /// ```
/// ///
/// Read the contents of a file into a [`String`] (you can also use [`read`]): /// Reads the contents of a file into a [`String`] (you can also use [`read`]):
/// ///
/// ```no_run /// ```no_run
/// use std::fs::File; /// use std::fs::File;
@ -229,7 +229,7 @@ pub struct DirBuilder {
recursive: bool, recursive: bool,
} }
/// Read the entire contents of a file into a bytes vector. /// Reads the entire contents of a file into a bytes vector.
/// ///
/// This is a convenience function for using [`File::open`] and [`read_to_end`] /// This is a convenience function for using [`File::open`] and [`read_to_end`]
/// with fewer imports and without an intermediate variable. /// with fewer imports and without an intermediate variable.
@ -268,7 +268,7 @@ pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
inner(path.as_ref()) inner(path.as_ref())
} }
/// Read the entire contents of a file into a string. /// Reads the entire contents of a file into a string.
/// ///
/// This is a convenience function for using [`File::open`] and [`read_to_string`] /// This is a convenience function for using [`File::open`] and [`read_to_string`]
/// with fewer imports and without an intermediate variable. /// with fewer imports and without an intermediate variable.
@ -311,7 +311,7 @@ pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> {
inner(path.as_ref()) inner(path.as_ref())
} }
/// Write a slice as the entire contents of a file. /// Writes a slice as the entire contents of a file.
/// ///
/// This function will create a file if it does not exist, /// This function will create a file if it does not exist,
/// and will entirely replace its contents if it does. /// and will entirely replace its contents if it does.
@ -767,7 +767,7 @@ fn buffer_capacity_required(mut file: &File) -> Option<usize> {
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
impl Read for &File { impl Read for &File {
/// Read some bytes from the file. /// Reads some bytes from the file.
/// ///
/// See [`Read::read`] docs for more info. /// See [`Read::read`] docs for more info.
/// ///
@ -835,7 +835,7 @@ impl Read for &File {
} }
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
impl Write for &File { impl Write for &File {
/// Write some bytes from the file. /// Writes some bytes from the file.
/// ///
/// See [`Write::write`] docs for more info. /// See [`Write::write`] docs for more info.
/// ///
@ -1526,7 +1526,7 @@ impl FromInner<fs_imp::FileAttr> for Metadata {
} }
impl FileTimes { impl FileTimes {
/// Create a new `FileTimes` with no times set. /// Creates a new `FileTimes` with no times set.
/// ///
/// Using the resulting `FileTimes` in [`File::set_times`] will not modify any timestamps. /// Using the resulting `FileTimes` in [`File::set_times`] will not modify any timestamps.
#[stable(feature = "file_set_times", since = "1.75.0")] #[stable(feature = "file_set_times", since = "1.75.0")]
@ -2005,7 +2005,7 @@ pub fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
fs_imp::unlink(path.as_ref()) fs_imp::unlink(path.as_ref())
} }
/// Given a path, query the file system to get information about a file, /// Given a path, queries the file system to get information about a file,
/// directory, etc. /// directory, etc.
/// ///
/// This function will traverse symbolic links to query information about the /// This function will traverse symbolic links to query information about the
@ -2044,7 +2044,7 @@ pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
fs_imp::stat(path.as_ref()).map(Metadata) fs_imp::stat(path.as_ref()).map(Metadata)
} }
/// Query the metadata about a file without following symlinks. /// Queries the metadata about a file without following symlinks.
/// ///
/// # Platform-specific behavior /// # Platform-specific behavior
/// ///
@ -2079,7 +2079,7 @@ pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
fs_imp::lstat(path.as_ref()).map(Metadata) fs_imp::lstat(path.as_ref()).map(Metadata)
} }
/// Rename a file or directory to a new name, replacing the original file if /// Renames a file or directory to a new name, replacing the original file if
/// `to` already exists. /// `to` already exists.
/// ///
/// This will not work if the new name is on a different mount point. /// This will not work if the new name is on a different mount point.

40
library/std/src/io/buffered/linewritershim.rs
View File

@ -2,6 +2,7 @@ use crate::io::{self, BufWriter, IoSlice, Write};
use core::slice::memchr; use core::slice::memchr;
/// Private helper struct for implementing the line-buffered writing logic. /// Private helper struct for implementing the line-buffered writing logic.
///
/// This shim temporarily wraps a BufWriter, and uses its internals to /// This shim temporarily wraps a BufWriter, and uses its internals to
/// implement a line-buffered writer (specifically by using the internal /// implement a line-buffered writer (specifically by using the internal
/// methods like write_to_buf and flush_buf). In this way, a more /// methods like write_to_buf and flush_buf). In this way, a more
@ -20,27 +21,27 @@ impl<'a, W: ?Sized + Write> LineWriterShim<'a, W> {
Self { buffer } Self { buffer }
} }
/// Get a reference to the inner writer (that is, the writer /// Gets a reference to the inner writer (that is, the writer
/// wrapped by the BufWriter). /// wrapped by the BufWriter).
fn inner(&self) -> &W { fn inner(&self) -> &W {
self.buffer.get_ref() self.buffer.get_ref()
} }
/// Get a mutable reference to the inner writer (that is, the writer /// Gets a mutable reference to the inner writer (that is, the writer
/// wrapped by the BufWriter). Be careful with this writer, as writes to /// wrapped by the BufWriter). Be careful with this writer, as writes to
/// it will bypass the buffer. /// it will bypass the buffer.
fn inner_mut(&mut self) -> &mut W { fn inner_mut(&mut self) -> &mut W {
self.buffer.get_mut() self.buffer.get_mut()
} }
/// Get the content currently buffered in self.buffer /// Gets the content currently buffered in self.buffer
fn buffered(&self) -> &[u8] { fn buffered(&self) -> &[u8] {
self.buffer.buffer() self.buffer.buffer()
} }
/// Flush the buffer iff the last byte is a newline (indicating that an /// Flushes the buffer iff the last byte is a newline (indicating that an
/// earlier write only succeeded partially, and we want to retry flushing /// earlier write only succeeded partially, and we want to retry flushing
/// the buffered line before continuing with a subsequent write) /// the buffered line before continuing with a subsequent write).
fn flush_if_completed_line(&mut self) -> io::Result<()> { fn flush_if_completed_line(&mut self) -> io::Result<()> {
match self.buffered().last().copied() { match self.buffered().last().copied() {
Some(b'\n') => self.buffer.flush_buf(), Some(b'\n') => self.buffer.flush_buf(),
@ -50,10 +51,11 @@ impl<'a, W: ?Sized + Write> LineWriterShim<'a, W> {
} }
impl<'a, W: ?Sized + Write> Write for LineWriterShim<'a, W> { impl<'a, W: ?Sized + Write> Write for LineWriterShim<'a, W> {
/// Write some data into this BufReader with line buffering. This means /// Writes some data into this BufReader with line buffering.
/// that, if any newlines are present in the data, the data up to the last ///
/// newline is sent directly to the underlying writer, and data after it /// This means that, if any newlines are present in the data, the data up to
/// is buffered. Returns the number of bytes written. /// the last newline is sent directly to the underlying writer, and data
/// after it is buffered. Returns the number of bytes written.
/// ///
/// This function operates on a "best effort basis"; in keeping with the /// This function operates on a "best effort basis"; in keeping with the
/// convention of `Write::write`, it makes at most one attempt to write /// convention of `Write::write`, it makes at most one attempt to write
@ -136,11 +138,12 @@ impl<'a, W: ?Sized + Write> Write for LineWriterShim<'a, W> {
self.buffer.flush() self.buffer.flush()
} }
/// Write some vectored data into this BufReader with line buffering. This /// Writes some vectored data into this BufReader with line buffering.
/// means that, if any newlines are present in the data, the data up to ///
/// and including the buffer containing the last newline is sent directly /// This means that, if any newlines are present in the data, the data up to
/// to the inner writer, and the data after it is buffered. Returns the /// and including the buffer containing the last newline is sent directly to
/// number of bytes written. /// the inner writer, and the data after it is buffered. Returns the number
/// of bytes written.
/// ///
/// This function operates on a "best effort basis"; in keeping with the /// This function operates on a "best effort basis"; in keeping with the
/// convention of `Write::write`, it makes at most one attempt to write /// convention of `Write::write`, it makes at most one attempt to write
@ -245,10 +248,11 @@ impl<'a, W: ?Sized + Write> Write for LineWriterShim<'a, W> {
self.inner().is_write_vectored() self.inner().is_write_vectored()
} }
/// Write some data into this BufReader with line buffering. This means /// Writes some data into this BufReader with line buffering.
/// that, if any newlines are present in the data, the data up to the last ///
/// newline is sent directly to the underlying writer, and data after it /// This means that, if any newlines are present in the data, the data up to
/// is buffered. /// the last newline is sent directly to the underlying writer, and data
/// after it is buffered.
/// ///
/// Because this function attempts to send completed lines to the underlying /// Because this function attempts to send completed lines to the underlying
/// writer, it will also flush the existing buffer if it contains any /// writer, it will also flush the existing buffer if it contains any

2
library/std/src/io/buffered/mod.rs
View File

@ -48,7 +48,7 @@ pub use bufwriter::WriterPanicked;
pub struct IntoInnerError<W>(W, Error); pub struct IntoInnerError<W>(W, Error);
impl<W> IntoInnerError<W> { impl<W> IntoInnerError<W> {
/// Construct a new IntoInnerError /// Constructs a new IntoInnerError
fn new(writer: W, error: Error) -> Self { fn new(writer: W, error: Error) -> Self {
Self(writer, error) Self(writer, error)
} }

4
library/std/src/io/error.rs
View File

@ -167,7 +167,7 @@ impl SimpleMessage {
} }
} }
/// Create and return an `io::Error` for a given `ErrorKind` and constant /// Creates and returns an `io::Error` for a given `ErrorKind` and constant
/// message. This doesn't allocate. /// message. This doesn't allocate.
pub(crate) macro const_io_error($kind:expr, $message:expr $(,)?) { pub(crate) macro const_io_error($kind:expr, $message:expr $(,)?) {
$crate::io::error::Error::from_static_message({ $crate::io::error::Error::from_static_message({
@ -852,7 +852,7 @@ impl Error {
} }
} }
/// Attempt to downcast the custom boxed error to `E`. /// Attempts to downcast the custom boxed error to `E`.
/// ///
/// If this [`Error`] contains a custom boxed error, /// If this [`Error`] contains a custom boxed error,
/// then it would attempt downcasting on the boxed error, /// then it would attempt downcasting on the boxed error,

26
library/std/src/io/mod.rs
View File

@ -782,7 +782,7 @@ pub trait Read {
false false
} }
/// Read all bytes until EOF in this source, placing them into `buf`. /// Reads all bytes until EOF in this source, placing them into `buf`.
/// ///
/// All bytes read from this source will be appended to the specified buffer /// All bytes read from this source will be appended to the specified buffer
/// `buf`. This function will continuously call [`read()`] to append more data to /// `buf`. This function will continuously call [`read()`] to append more data to
@ -866,7 +866,7 @@ pub trait Read {
default_read_to_end(self, buf, None) default_read_to_end(self, buf, None)
} }
/// Read all bytes until EOF in this source, appending them to `buf`. /// Reads all bytes until EOF in this source, appending them to `buf`.
/// ///
/// If successful, this function returns the number of bytes which were read /// If successful, this function returns the number of bytes which were read
/// and appended to `buf`. /// and appended to `buf`.
@ -909,7 +909,7 @@ pub trait Read {
default_read_to_string(self, buf, None) default_read_to_string(self, buf, None)
} }
/// Read the exact number of bytes required to fill `buf`. /// Reads the exact number of bytes required to fill `buf`.
/// ///
/// This function reads as many bytes as necessary to completely fill the /// This function reads as many bytes as necessary to completely fill the
/// specified buffer `buf`. /// specified buffer `buf`.
@ -973,7 +973,7 @@ pub trait Read {
default_read_buf(|b| self.read(b), buf) default_read_buf(|b| self.read(b), buf)
} }
/// Read the exact number of bytes required to fill `cursor`. /// Reads the exact number of bytes required to fill `cursor`.
/// ///
/// This is similar to the [`read_exact`](Read::read_exact) method, except /// This is similar to the [`read_exact`](Read::read_exact) method, except
/// that it is passed a [`BorrowedCursor`] rather than `[u8]` to allow use /// that it is passed a [`BorrowedCursor`] rather than `[u8]` to allow use
@ -1159,7 +1159,7 @@ pub trait Read {
} }
} }
/// Read all bytes from a [reader][Read] into a new [`String`]. /// Reads all bytes from a [reader][Read] into a new [`String`].
/// ///
/// This is a convenience function for [`Read::read_to_string`]. Using this /// This is a convenience function for [`Read::read_to_string`]. Using this
/// function avoids having to create a variable first and provides more type /// function avoids having to create a variable first and provides more type
@ -1212,7 +1212,7 @@ pub fn read_to_string<R: Read>(mut reader: R) -> Result<String> {
/// A buffer type used with `Read::read_vectored`. /// A buffer type used with `Read::read_vectored`.
/// ///
/// It is semantically a wrapper around an `&mut [u8]`, but is guaranteed to be /// It is semantically a wrapper around a `&mut [u8]`, but is guaranteed to be
/// ABI compatible with the `iovec` type on Unix platforms and `WSABUF` on /// ABI compatible with the `iovec` type on Unix platforms and `WSABUF` on
/// Windows. /// Windows.
#[stable(feature = "iovec", since = "1.36.0")] #[stable(feature = "iovec", since = "1.36.0")]
@ -1531,7 +1531,7 @@ impl<'a> Deref for IoSlice<'a> {
#[doc(notable_trait)] #[doc(notable_trait)]
#[cfg_attr(not(test), rustc_diagnostic_item = "IoWrite")] #[cfg_attr(not(test), rustc_diagnostic_item = "IoWrite")]
pub trait Write { pub trait Write {
/// Write a buffer into this writer, returning how many bytes were written. /// Writes a buffer into this writer, returning how many bytes were written.
/// ///
/// This function will attempt to write the entire contents of `buf`, but /// This function will attempt to write the entire contents of `buf`, but
/// the entire write might not succeed, or the write may also generate an /// the entire write might not succeed, or the write may also generate an
@ -1630,7 +1630,7 @@ pub trait Write {
false false
} }
/// Flush this output stream, ensuring that all intermediately buffered /// Flushes this output stream, ensuring that all intermediately buffered
/// contents reach their destination. /// contents reach their destination.
/// ///
/// # Errors /// # Errors
@ -2247,7 +2247,7 @@ pub trait BufRead: Read {
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
fn consume(&mut self, amt: usize); fn consume(&mut self, amt: usize);
/// Check if the underlying `Read` has any data left to be read. /// Checks if the underlying `Read` has any data left to be read.
/// ///
/// This function may fill the buffer to check for data, /// This function may fill the buffer to check for data,
/// so this functions returns `Result<bool>`, not `bool`. /// so this functions returns `Result<bool>`, not `bool`.
@ -2278,7 +2278,7 @@ pub trait BufRead: Read {
self.fill_buf().map(|b| !b.is_empty()) self.fill_buf().map(|b| !b.is_empty())
} }
/// Read all bytes into `buf` until the delimiter `byte` or EOF is reached. /// Reads all bytes into `buf` until the delimiter `byte` or EOF is reached.
/// ///
/// This function will read bytes from the underlying stream until the /// This function will read bytes from the underlying stream until the
/// delimiter or EOF is found. Once found, all bytes up to, and including, /// delimiter or EOF is found. Once found, all bytes up to, and including,
@ -2337,7 +2337,7 @@ pub trait BufRead: Read {
read_until(self, byte, buf) read_until(self, byte, buf)
} }
/// Skip all bytes until the delimiter `byte` or EOF is reached. /// Skips all bytes until the delimiter `byte` or EOF is reached.
/// ///
/// This function will read (and discard) bytes from the underlying stream until the /// This function will read (and discard) bytes from the underlying stream until the
/// delimiter or EOF is found. /// delimiter or EOF is found.
@ -2399,7 +2399,7 @@ pub trait BufRead: Read {
skip_until(self, byte) skip_until(self, byte)
} }
/// Read all bytes until a newline (the `0xA` byte) is reached, and append /// Reads all bytes until a newline (the `0xA` byte) is reached, and append
/// them to the provided `String` buffer. /// them to the provided `String` buffer.
/// ///
/// Previous content of the buffer will be preserved. To avoid appending to /// Previous content of the buffer will be preserved. To avoid appending to
@ -3038,7 +3038,7 @@ where
} }
} }
/// Read a single byte in a slow, generic way. This is used by the default /// Reads a single byte in a slow, generic way. This is used by the default
/// `spec_read_byte`. /// `spec_read_byte`.
#[inline] #[inline]
fn inlined_slow_read_byte<R: Read>(reader: &mut R) -> Option<Result<u8>> { fn inlined_slow_read_byte<R: Read>(reader: &mut R) -> Option<Result<u8>> {

2
library/std/src/io/stdio.rs
View File

@ -1092,7 +1092,7 @@ pub fn try_set_output_capture(
OUTPUT_CAPTURE.try_with(move |slot| slot.replace(sink)) OUTPUT_CAPTURE.try_with(move |slot| slot.replace(sink))
} }
/// Write `args` to the capture buffer if enabled and possible, or `global_s` /// Writes `args` to the capture buffer if enabled and possible, or `global_s`
/// otherwise. `label` identifies the stream in a panic message. /// otherwise. `label` identifies the stream in a panic message.
/// ///
/// This function is used to print error messages, so it takes extra /// This function is used to print error messages, so it takes extra

2
library/std/src/io/tests.rs
View File

@ -530,7 +530,7 @@ fn io_slice_advance_slices_beyond_total_length() {
assert!(bufs.is_empty()); assert!(bufs.is_empty());
} }
/// Create a new writer that reads from at most `n_bufs` and reads /// Creates a new writer that reads from at most `n_bufs` and reads
/// `per_call` bytes (in total) per call to write. /// `per_call` bytes (in total) per call to write.
fn test_writer(n_bufs: usize, per_call: usize) -> TestWriter { fn test_writer(n_bufs: usize, per_call: usize) -> TestWriter {
TestWriter { n_bufs, per_call, written: Vec::new() } TestWriter { n_bufs, per_call, written: Vec::new() }

4
library/std/src/keyword_docs.rs
View File

@ -1175,7 +1175,7 @@ mod ref_keyword {}
#[doc(keyword = "return")] #[doc(keyword = "return")]
// //
/// Return a value from a function. /// Returns a value from a function.
/// ///
/// A `return` marks the end of an execution path in a function: /// A `return` marks the end of an execution path in a function:
/// ///
@ -2310,7 +2310,7 @@ mod where_keyword {}
#[doc(alias = "promise")] #[doc(alias = "promise")]
#[doc(keyword = "async")] #[doc(keyword = "async")]
// //
/// Return a [`Future`] instead of blocking the current thread. /// Returns a [`Future`] instead of blocking the current thread.
/// ///
/// Use `async` in front of `fn`, `closure`, or a `block` to turn the marked code into a `Future`. /// Use `async` in front of `fn`, `closure`, or a `block` to turn the marked code into a `Future`.
/// As such the code will not be run immediately, but will only be evaluated when the returned /// As such the code will not be run immediately, but will only be evaluated when the returned

2
library/std/src/os/fd/owned.rs
View File

@ -70,7 +70,7 @@ pub struct OwnedFd {
} }
impl BorrowedFd<'_> { impl BorrowedFd<'_> {
/// Return a `BorrowedFd` holding the given raw file descriptor. /// Returns a `BorrowedFd` holding the given raw file descriptor.
/// ///
/// # Safety /// # Safety
/// ///

2
library/std/src/os/freebsd/net.rs
View File

@ -42,7 +42,7 @@ pub trait UnixSocketExt: Sealed {
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
fn set_local_creds_persistent(&self, local_creds_persistent: bool) -> io::Result<()>; fn set_local_creds_persistent(&self, local_creds_persistent: bool) -> io::Result<()>;
/// Get a filter name if one had been set previously on the socket. /// Gets a filter name if one had been set previously on the socket.
#[unstable(feature = "acceptfilter", issue = "121891")] #[unstable(feature = "acceptfilter", issue = "121891")]
fn acceptfilter(&self) -> io::Result<&CStr>; fn acceptfilter(&self) -> io::Result<&CStr>;

2
library/std/src/os/netbsd/net.rs
View File

@ -42,7 +42,7 @@ pub trait UnixSocketExt: Sealed {
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
fn set_local_creds(&self, local_creds: bool) -> io::Result<()>; fn set_local_creds(&self, local_creds: bool) -> io::Result<()>;
/// Get a filter name if one had been set previously on the socket. /// Gets a filter name if one had been set previously on the socket.
#[unstable(feature = "acceptfilter", issue = "121891")] #[unstable(feature = "acceptfilter", issue = "121891")]
fn acceptfilter(&self) -> io::Result<&CStr>; fn acceptfilter(&self) -> io::Result<&CStr>;

2
library/std/src/os/solid/io.rs
View File

@ -98,7 +98,7 @@ pub struct OwnedFd {
} }
impl BorrowedFd<'_> { impl BorrowedFd<'_> {
/// Return a `BorrowedFd` holding the given raw file descriptor. /// Returns a `BorrowedFd` holding the given raw file descriptor.
/// ///
/// # Safety /// # Safety
/// ///

24
library/std/src/os/uefi/env.rs
View File

@ -26,7 +26,7 @@ static BOOT_SERVICES_FLAG: AtomicBool = AtomicBool::new(false);
/// standard library is loaded. /// standard library is loaded.
/// ///
/// # SAFETY /// # SAFETY
/// Calling this function more than once will panic /// Calling this function more than once will panic.
pub(crate) unsafe fn init_globals(handle: NonNull<c_void>, system_table: NonNull<c_void>) { pub(crate) unsafe fn init_globals(handle: NonNull<c_void>, system_table: NonNull<c_void>) {
IMAGE_HANDLE IMAGE_HANDLE
.compare_exchange( .compare_exchange(
@ -47,23 +47,25 @@ pub(crate) unsafe fn init_globals(handle: NonNull<c_void>, system_table: NonNull
BOOT_SERVICES_FLAG.store(true, Ordering::Release) BOOT_SERVICES_FLAG.store(true, Ordering::Release)
} }
/// Get the SystemTable Pointer. /// Gets the SystemTable Pointer.
///
/// If you want to use `BootServices` then please use [`boot_services`] as it performs some /// If you want to use `BootServices` then please use [`boot_services`] as it performs some
/// additional checks. /// additional checks.
/// ///
/// Note: This function panics if the System Table or Image Handle is not initialized /// Note: This function panics if the System Table or Image Handle is not initialized.
pub fn system_table() -> NonNull<c_void> { pub fn system_table() -> NonNull<c_void> {
try_system_table().unwrap() try_system_table().unwrap()
} }
/// Get the ImageHandle Pointer. /// Gets the ImageHandle Pointer.
/// ///
/// Note: This function panics if the System Table or Image Handle is not initialized /// Note: This function panics if the System Table or Image Handle is not initialized.
pub fn image_handle() -> NonNull<c_void> { pub fn image_handle() -> NonNull<c_void> {
try_image_handle().unwrap() try_image_handle().unwrap()
} }
/// Get the BootServices Pointer. /// Gets the BootServices Pointer.
///
/// This function also checks if `ExitBootServices` has already been called. /// This function also checks if `ExitBootServices` has already been called.
pub fn boot_services() -> Option<NonNull<c_void>> { pub fn boot_services() -> Option<NonNull<c_void>> {
if BOOT_SERVICES_FLAG.load(Ordering::Acquire) { if BOOT_SERVICES_FLAG.load(Ordering::Acquire) {
@ -75,14 +77,16 @@ pub fn boot_services() -> Option<NonNull<c_void>> {
} }
} }
/// Get the SystemTable Pointer. /// Gets the SystemTable Pointer.
/// This function is mostly intended for places where panic is not an option ///
/// This function is mostly intended for places where panic is not an option.
pub(crate) fn try_system_table() -> Option<NonNull<c_void>> { pub(crate) fn try_system_table() -> Option<NonNull<c_void>> {
NonNull::new(SYSTEM_TABLE.load(Ordering::Acquire)) NonNull::new(SYSTEM_TABLE.load(Ordering::Acquire))
} }
/// Get the SystemHandle Pointer. /// Gets the SystemHandle Pointer.
/// This function is mostly intended for places where panicking is not an option ///
/// This function is mostly intended for places where panicking is not an option.
pub(crate) fn try_image_handle() -> Option<NonNull<c_void>> { pub(crate) fn try_image_handle() -> Option<NonNull<c_void>> {
NonNull::new(IMAGE_HANDLE.load(Ordering::Acquire)) NonNull::new(IMAGE_HANDLE.load(Ordering::Acquire))
} }

32
library/std/src/os/unix/net/ancillary.rs
View File

@ -164,7 +164,7 @@ struct AncillaryDataIter<'a, T> {
} }
impl<'a, T> AncillaryDataIter<'a, T> { impl<'a, T> AncillaryDataIter<'a, T> {
/// Create `AncillaryDataIter` struct to iterate through the data unit in the control message. /// Creates `AncillaryDataIter` struct to iterate through the data unit in the control message.
/// ///
/// # Safety /// # Safety
/// ///
@ -220,7 +220,7 @@ pub struct SocketCred(libc::sockcred2);
#[doc(cfg(any(target_os = "android", target_os = "linux")))] #[doc(cfg(any(target_os = "android", target_os = "linux")))]
#[cfg(any(target_os = "android", target_os = "linux"))] #[cfg(any(target_os = "android", target_os = "linux"))]
impl SocketCred { impl SocketCred {
/// Create a Unix credential struct. /// Creates a Unix credential struct.
/// ///
/// PID, UID and GID is set to 0. /// PID, UID and GID is set to 0.
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
@ -235,7 +235,7 @@ impl SocketCred {
self.0.pid = pid; self.0.pid = pid;
} }
/// Get the current PID. /// Gets the current PID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_pid(&self) -> libc::pid_t { pub fn get_pid(&self) -> libc::pid_t {
@ -248,7 +248,7 @@ impl SocketCred {
self.0.uid = uid; self.0.uid = uid;
} }
/// Get the current UID. /// Gets the current UID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_uid(&self) -> libc::uid_t { pub fn get_uid(&self) -> libc::uid_t {
@ -261,7 +261,7 @@ impl SocketCred {
self.0.gid = gid; self.0.gid = gid;
} }
/// Get the current GID. /// Gets the current GID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_gid(&self) -> libc::gid_t { pub fn get_gid(&self) -> libc::gid_t {
@ -271,7 +271,7 @@ impl SocketCred {
#[cfg(target_os = "freebsd")] #[cfg(target_os = "freebsd")]
impl SocketCred { impl SocketCred {
/// Create a Unix credential struct. /// Creates a Unix credential struct.
/// ///
/// PID, UID and GID is set to 0. /// PID, UID and GID is set to 0.
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
@ -295,7 +295,7 @@ impl SocketCred {
self.0.sc_pid = pid; self.0.sc_pid = pid;
} }
/// Get the current PID. /// Gets the current PID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_pid(&self) -> libc::pid_t { pub fn get_pid(&self) -> libc::pid_t {
@ -308,7 +308,7 @@ impl SocketCred {
self.0.sc_euid = uid; self.0.sc_euid = uid;
} }
/// Get the current UID. /// Gets the current UID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_uid(&self) -> libc::uid_t { pub fn get_uid(&self) -> libc::uid_t {
@ -321,7 +321,7 @@ impl SocketCred {
self.0.sc_egid = gid; self.0.sc_egid = gid;
} }
/// Get the current GID. /// Gets the current GID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_gid(&self) -> libc::gid_t { pub fn get_gid(&self) -> libc::gid_t {
@ -331,7 +331,7 @@ impl SocketCred {
#[cfg(target_os = "netbsd")] #[cfg(target_os = "netbsd")]
impl SocketCred { impl SocketCred {
/// Create a Unix credential struct. /// Creates a Unix credential struct.
/// ///
/// PID, UID and GID is set to 0. /// PID, UID and GID is set to 0.
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
@ -353,7 +353,7 @@ impl SocketCred {
self.0.sc_pid = pid; self.0.sc_pid = pid;
} }
/// Get the current PID. /// Gets the current PID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_pid(&self) -> libc::pid_t { pub fn get_pid(&self) -> libc::pid_t {
@ -366,7 +366,7 @@ impl SocketCred {
self.0.sc_uid = uid; self.0.sc_uid = uid;
} }
/// Get the current UID. /// Gets the current UID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_uid(&self) -> libc::uid_t { pub fn get_uid(&self) -> libc::uid_t {
@ -379,7 +379,7 @@ impl SocketCred {
self.0.sc_gid = gid; self.0.sc_gid = gid;
} }
/// Get the current GID. /// Gets the current GID.
#[must_use] #[must_use]
#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")]
pub fn get_gid(&self) -> libc::gid_t { pub fn get_gid(&self) -> libc::gid_t {
@ -466,7 +466,7 @@ pub enum AncillaryData<'a> {
} }
impl<'a> AncillaryData<'a> { impl<'a> AncillaryData<'a> {
/// Create an `AncillaryData::ScmRights` variant. /// Creates an `AncillaryData::ScmRights` variant.
/// ///
/// # Safety /// # Safety
/// ///
@ -478,7 +478,7 @@ impl<'a> AncillaryData<'a> {
AncillaryData::ScmRights(scm_rights) AncillaryData::ScmRights(scm_rights)
} }
/// Create an `AncillaryData::ScmCredentials` variant. /// Creates an `AncillaryData::ScmCredentials` variant.
/// ///
/// # Safety /// # Safety
/// ///
@ -605,7 +605,7 @@ pub struct SocketAncillary<'a> {
} }
impl<'a> SocketAncillary<'a> { impl<'a> SocketAncillary<'a> {
/// Create an ancillary data with the given buffer. /// Creates an ancillary data with the given buffer.
/// ///
/// # Example /// # Example
/// ///

6
library/std/src/os/unix/process.rs
View File

@ -444,7 +444,7 @@ impl From<crate::process::ChildStdin> for OwnedFd {
} }
} }
/// Create a `ChildStdin` from the provided `OwnedFd`. /// Creates a `ChildStdin` from the provided `OwnedFd`.
/// ///
/// The provided file descriptor must point to a pipe /// The provided file descriptor must point to a pipe
/// with the `CLOEXEC` flag set. /// with the `CLOEXEC` flag set.
@ -475,7 +475,7 @@ impl From<crate::process::ChildStdout> for OwnedFd {
} }
} }
/// Create a `ChildStdout` from the provided `OwnedFd`. /// Creates a `ChildStdout` from the provided `OwnedFd`.
/// ///
/// The provided file descriptor must point to a pipe /// The provided file descriptor must point to a pipe
/// with the `CLOEXEC` flag set. /// with the `CLOEXEC` flag set.
@ -506,7 +506,7 @@ impl From<crate::process::ChildStderr> for OwnedFd {
} }
} }
/// Create a `ChildStderr` from the provided `OwnedFd`. /// Creates a `ChildStderr` from the provided `OwnedFd`.
/// ///
/// The provided file descriptor must point to a pipe /// The provided file descriptor must point to a pipe
/// with the `CLOEXEC` flag set. /// with the `CLOEXEC` flag set.

26
library/std/src/os/wasi/fs.rs
View File

@ -169,55 +169,55 @@ pub trait FileExt {
#[doc(alias = "fd_tell")] #[doc(alias = "fd_tell")]
fn tell(&self) -> io::Result<u64>; fn tell(&self) -> io::Result<u64>;
/// Adjust the flags associated with this file. /// Adjusts the flags associated with this file.
/// ///
/// This corresponds to the `fd_fdstat_set_flags` syscall. /// This corresponds to the `fd_fdstat_set_flags` syscall.
#[doc(alias = "fd_fdstat_set_flags")] #[doc(alias = "fd_fdstat_set_flags")]
fn fdstat_set_flags(&self, flags: u16) -> io::Result<()>; fn fdstat_set_flags(&self, flags: u16) -> io::Result<()>;
/// Adjust the rights associated with this file. /// Adjusts the rights associated with this file.
/// ///
/// This corresponds to the `fd_fdstat_set_rights` syscall. /// This corresponds to the `fd_fdstat_set_rights` syscall.
#[doc(alias = "fd_fdstat_set_rights")] #[doc(alias = "fd_fdstat_set_rights")]
fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()>; fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()>;
/// Provide file advisory information on a file descriptor. /// Provides file advisory information on a file descriptor.
/// ///
/// This corresponds to the `fd_advise` syscall. /// This corresponds to the `fd_advise` syscall.
#[doc(alias = "fd_advise")] #[doc(alias = "fd_advise")]
fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()>; fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()>;
/// Force the allocation of space in a file. /// Forces the allocation of space in a file.
/// ///
/// This corresponds to the `fd_allocate` syscall. /// This corresponds to the `fd_allocate` syscall.
#[doc(alias = "fd_allocate")] #[doc(alias = "fd_allocate")]
fn allocate(&self, offset: u64, len: u64) -> io::Result<()>; fn allocate(&self, offset: u64, len: u64) -> io::Result<()>;
/// Create a directory. /// Creates a directory.
/// ///
/// This corresponds to the `path_create_directory` syscall. /// This corresponds to the `path_create_directory` syscall.
#[doc(alias = "path_create_directory")] #[doc(alias = "path_create_directory")]
fn create_directory<P: AsRef<Path>>(&self, dir: P) -> io::Result<()>; fn create_directory<P: AsRef<Path>>(&self, dir: P) -> io::Result<()>;
/// Read the contents of a symbolic link. /// Reads the contents of a symbolic link.
/// ///
/// This corresponds to the `path_readlink` syscall. /// This corresponds to the `path_readlink` syscall.
#[doc(alias = "path_readlink")] #[doc(alias = "path_readlink")]
fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf>; fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf>;
/// Return the attributes of a file or directory. /// Returns the attributes of a file or directory.
/// ///
/// This corresponds to the `path_filestat_get` syscall. /// This corresponds to the `path_filestat_get` syscall.
#[doc(alias = "path_filestat_get")] #[doc(alias = "path_filestat_get")]
fn metadata_at<P: AsRef<Path>>(&self, lookup_flags: u32, path: P) -> io::Result<Metadata>; fn metadata_at<P: AsRef<Path>>(&self, lookup_flags: u32, path: P) -> io::Result<Metadata>;
/// Unlink a file. /// Unlinks a file.
/// ///
/// This corresponds to the `path_unlink_file` syscall. /// This corresponds to the `path_unlink_file` syscall.
#[doc(alias = "path_unlink_file")] #[doc(alias = "path_unlink_file")]
fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()>; fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()>;
/// Remove a directory. /// Removes a directory.
/// ///
/// This corresponds to the `path_remove_directory` syscall. /// This corresponds to the `path_remove_directory` syscall.
#[doc(alias = "path_remove_directory")] #[doc(alias = "path_remove_directory")]
@ -501,7 +501,7 @@ impl DirEntryExt for fs::DirEntry {
} }
} }
/// Create a hard link. /// Creates a hard link.
/// ///
/// This corresponds to the `path_link` syscall. /// This corresponds to the `path_link` syscall.
#[doc(alias = "path_link")] #[doc(alias = "path_link")]
@ -520,7 +520,7 @@ pub fn link<P: AsRef<Path>, U: AsRef<Path>>(
) )
} }
/// Rename a file or directory. /// Renames a file or directory.
/// ///
/// This corresponds to the `path_rename` syscall. /// This corresponds to the `path_rename` syscall.
#[doc(alias = "path_rename")] #[doc(alias = "path_rename")]
@ -537,7 +537,7 @@ pub fn rename<P: AsRef<Path>, U: AsRef<Path>>(
) )
} }
/// Create a symbolic link. /// Creates a symbolic link.
/// ///
/// This corresponds to the `path_symlink` syscall. /// This corresponds to the `path_symlink` syscall.
#[doc(alias = "path_symlink")] #[doc(alias = "path_symlink")]
@ -551,7 +551,7 @@ pub fn symlink<P: AsRef<Path>, U: AsRef<Path>>(
.symlink(osstr2str(old_path.as_ref().as_ref())?, osstr2str(new_path.as_ref().as_ref())?) .symlink(osstr2str(old_path.as_ref().as_ref())?, osstr2str(new_path.as_ref().as_ref())?)
} }
/// Create a symbolic link. /// Creates a symbolic link.
/// ///
/// This is a convenience API similar to `std::os::unix::fs::symlink` and /// This is a convenience API similar to `std::os::unix::fs::symlink` and
/// `std::os::windows::fs::symlink_file` and `std::os::windows::fs::symlink_dir`. /// `std::os::windows::fs::symlink_file` and `std::os::windows::fs::symlink_dir`.

2
library/std/src/os/windows/fs.rs
View File

@ -631,7 +631,7 @@ pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::
sys::fs::symlink_inner(original.as_ref(), link.as_ref(), true) sys::fs::symlink_inner(original.as_ref(), link.as_ref(), true)
} }
/// Create a junction point. /// Creates a junction point.
/// ///
/// The `link` path will be a directory junction pointing to the original path. /// The `link` path will be a directory junction pointing to the original path.
/// If `link` is a relative path then it will be made absolute prior to creating the junction point. /// If `link` is a relative path then it will be made absolute prior to creating the junction point.

2
library/std/src/os/windows/io/handle.rs
View File

@ -135,7 +135,7 @@ unsafe impl Sync for HandleOrInvalid {}
unsafe impl Sync for BorrowedHandle<'_> {} unsafe impl Sync for BorrowedHandle<'_> {}
impl BorrowedHandle<'_> { impl BorrowedHandle<'_> {
/// Return a `BorrowedHandle` holding the given raw handle. /// Returns a `BorrowedHandle` holding the given raw handle.
/// ///
/// # Safety /// # Safety
/// ///

2
library/std/src/os/windows/io/raw.rs
View File

@ -44,7 +44,7 @@ pub trait AsRawHandle {
fn as_raw_handle(&self) -> RawHandle; fn as_raw_handle(&self) -> RawHandle;
} }
/// Construct I/O objects from raw handles. /// Constructs I/O objects from raw handles.
#[stable(feature = "from_raw_os", since = "1.1.0")] #[stable(feature = "from_raw_os", since = "1.1.0")]
pub trait FromRawHandle { pub trait FromRawHandle {
/// Constructs a new I/O object from the specified raw handle. /// Constructs a new I/O object from the specified raw handle.

2
library/std/src/os/windows/io/socket.rs
View File

@ -63,7 +63,7 @@ pub struct OwnedSocket {
} }
impl BorrowedSocket<'_> { impl BorrowedSocket<'_> {
/// Return a `BorrowedSocket` holding the given raw socket. /// Returns a `BorrowedSocket` holding the given raw socket.
/// ///
/// # Safety /// # Safety
/// ///

6
library/std/src/os/windows/process.rs
View File

@ -109,7 +109,7 @@ impl IntoRawHandle for process::ChildStderr {
} }
} }
/// Create a `ChildStdin` from the provided `OwnedHandle`. /// Creates a `ChildStdin` from the provided `OwnedHandle`.
/// ///
/// The provided handle must be asynchronous, as reading and /// The provided handle must be asynchronous, as reading and
/// writing from and to it is implemented using asynchronous APIs. /// writing from and to it is implemented using asynchronous APIs.
@ -122,7 +122,7 @@ impl From<OwnedHandle> for process::ChildStdin {
} }
} }
/// Create a `ChildStdout` from the provided `OwnedHandle`. /// Creates a `ChildStdout` from the provided `OwnedHandle`.
/// ///
/// The provided handle must be asynchronous, as reading and /// The provided handle must be asynchronous, as reading and
/// writing from and to it is implemented using asynchronous APIs. /// writing from and to it is implemented using asynchronous APIs.
@ -135,7 +135,7 @@ impl From<OwnedHandle> for process::ChildStdout {
} }
} }
/// Create a `ChildStderr` from the provided `OwnedHandle`. /// Creates a `ChildStderr` from the provided `OwnedHandle`.
/// ///
/// The provided handle must be asynchronous, as reading and /// The provided handle must be asynchronous, as reading and
/// writing from and to it is implemented using asynchronous APIs. /// writing from and to it is implemented using asynchronous APIs.

33
library/std/src/os/xous/ffi.rs
View File

@ -274,7 +274,7 @@ fn connect_impl(address: ServerAddress, blocking: bool) -> Result<Connection, Er
} }
} }
/// Connect to a Xous server represented by the specified `address`. /// Connects to a Xous server represented by the specified `address`.
/// ///
/// The current thread will block until the server is available. Returns /// The current thread will block until the server is available. Returns
/// an error if the server cannot accept any more connections. /// an error if the server cannot accept any more connections.
@ -282,7 +282,7 @@ pub(crate) fn connect(address: ServerAddress) -> Result<Connection, Error> {
connect_impl(address, true) connect_impl(address, true)
} }
/// Attempt to connect to a Xous server represented by the specified `address`. /// Attempts to connect to a Xous server represented by the specified `address`.
/// ///
/// If the server does not exist then None is returned. /// If the server does not exist then None is returned.
pub(crate) fn try_connect(address: ServerAddress) -> Result<Option<Connection>, Error> { pub(crate) fn try_connect(address: ServerAddress) -> Result<Option<Connection>, Error> {
@ -293,7 +293,7 @@ pub(crate) fn try_connect(address: ServerAddress) -> Result<Option<Connection>,
} }
} }
/// Terminate the current process and return the specified code to the parent process. /// Terminates the current process and returns the specified code to the parent process.
pub(crate) fn exit(return_code: u32) -> ! { pub(crate) fn exit(return_code: u32) -> ! {
let a0 = Syscall::TerminateProcess as usize; let a0 = Syscall::TerminateProcess as usize;
let a1 = return_code as usize; let a1 = return_code as usize;
@ -320,7 +320,7 @@ pub(crate) fn exit(return_code: u32) -> ! {
unreachable!(); unreachable!();
} }
/// Suspend the current thread and allow another thread to run. This thread may /// Suspends the current thread and allow another thread to run. This thread may
/// continue executing again immediately if there are no other threads available /// continue executing again immediately if there are no other threads available
/// to run on the system. /// to run on the system.
pub(crate) fn do_yield() { pub(crate) fn do_yield() {
@ -348,9 +348,11 @@ pub(crate) fn do_yield() {
}; };
} }
/// Allocate memory from the system. An optional physical and/or virtual address /// Allocates memory from the system.
/// may be specified in order to ensure memory is allocated at specific offsets, ///
/// otherwise the kernel will select an address. /// An optional physical and/or virtual address may be specified in order to
/// ensure memory is allocated at specific offsets, otherwise the kernel will
/// select an address.
/// ///
/// # Safety /// # Safety
/// ///
@ -400,7 +402,7 @@ pub(crate) unsafe fn map_memory<T>(
} }
} }
/// Destroy the given memory, returning it to the compiler. /// Destroys the given memory, returning it to the compiler.
/// ///
/// Safety: The memory pointed to by `range` should not be used after this /// Safety: The memory pointed to by `range` should not be used after this
/// function returns, even if this function returns Err(). /// function returns, even if this function returns Err().
@ -439,9 +441,10 @@ pub(crate) unsafe fn unmap_memory<T>(range: *mut [T]) -> Result<(), Error> {
} }
} }
/// Adjust the memory flags for the given range. This can be used to remove flags /// Adjusts the memory flags for the given range.
/// from a given region in order to harden memory access. Note that flags may ///
/// only be removed and may never be added. /// This can be used to remove flags from a given region in order to harden
/// memory access. Note that flags may only be removed and may never be added.
/// ///
/// Safety: The memory pointed to by `range` may become inaccessible or have its /// Safety: The memory pointed to by `range` may become inaccessible or have its
/// mutability removed. It is up to the caller to ensure that the flags specified /// mutability removed. It is up to the caller to ensure that the flags specified
@ -484,7 +487,7 @@ pub(crate) unsafe fn update_memory_flags<T>(
} }
} }
/// Create a thread with a given stack and up to four arguments /// Creates a thread with a given stack and up to four arguments.
pub(crate) fn create_thread( pub(crate) fn create_thread(
start: *mut usize, start: *mut usize,
stack: *mut [u8], stack: *mut [u8],
@ -527,7 +530,7 @@ pub(crate) fn create_thread(
} }
} }
/// Wait for the given thread to terminate and return the exit code from that thread. /// Waits for the given thread to terminate and returns the exit code from that thread.
pub(crate) fn join_thread(thread_id: ThreadId) -> Result<usize, Error> { pub(crate) fn join_thread(thread_id: ThreadId) -> Result<usize, Error> {
let mut a0 = Syscall::JoinThread as usize; let mut a0 = Syscall::JoinThread as usize;
let mut a1 = thread_id.into(); let mut a1 = thread_id.into();
@ -567,7 +570,7 @@ pub(crate) fn join_thread(thread_id: ThreadId) -> Result<usize, Error> {
} }
} }
/// Get the current thread's ID /// Gets the current thread's ID.
pub(crate) fn thread_id() -> Result<ThreadId, Error> { pub(crate) fn thread_id() -> Result<ThreadId, Error> {
let mut a0 = Syscall::GetThreadId as usize; let mut a0 = Syscall::GetThreadId as usize;
let mut a1 = 0; let mut a1 = 0;
@ -603,7 +606,7 @@ pub(crate) fn thread_id() -> Result<ThreadId, Error> {
} }
} }
/// Adjust the given `knob` limit to match the new value `new`. The current value must /// Adjusts the given `knob` limit to match the new value `new`. The current value must
/// match the `current` in order for this to take effect. /// match the `current` in order for this to take effect.
/// ///
/// The new value is returned as a result of this call. If the call fails, then the old /// The new value is returned as a result of this call. If the call fails, then the old

6
library/std/src/os/xous/services.rs
View File

@ -83,7 +83,7 @@ mod ns {
} }
} }
/// Attempt to connect to a server by name. If the server does not exist, this will /// Attempts to connect to a server by name. If the server does not exist, this will
/// block until the server is created. /// block until the server is created.
/// ///
/// Note that this is different from connecting to a server by address. Server /// Note that this is different from connecting to a server by address. Server
@ -94,7 +94,7 @@ pub fn connect(name: &str) -> Option<Connection> {
ns::connect_with_name(name) ns::connect_with_name(name)
} }
/// Attempt to connect to a server by name. If the server does not exist, this will /// Attempts to connect to a server by name. If the server does not exist, this will
/// immediately return `None`. /// immediately return `None`.
/// ///
/// Note that this is different from connecting to a server by address. Server /// Note that this is different from connecting to a server by address. Server
@ -107,7 +107,7 @@ pub fn try_connect(name: &str) -> Option<Connection> {
static NAME_SERVER_CONNECTION: AtomicU32 = AtomicU32::new(0); static NAME_SERVER_CONNECTION: AtomicU32 = AtomicU32::new(0);
/// Return a `Connection` to the name server. If the name server has not been started, /// Returns a `Connection` to the name server. If the name server has not been started,
/// then this call will block until the name server has been started. The `Connection` /// then this call will block until the name server has been started. The `Connection`
/// will be shared among all connections in a process, so it is safe to call this /// will be shared among all connections in a process, so it is safe to call this
/// multiple times. /// multiple times.

Some files were not shown because too many files have changed in this diff Show More