Fix doc nits

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

library/std/src/sys/pal/itron/error.rs

@@ -9,7 +9,7 @@ pub struct ItronError {
 }
 
 impl ItronError {
-    /// Construct `ItronError` from the specified error code. Returns `None` if the
+    /// Constructs `ItronError` from the specified error code. Returns `None` if the
     /// error code does not represent a failure or warning.
     #[inline]
     pub fn new(er: abi::ER) -> Option<Self> {
@@ -22,7 +22,7 @@ impl ItronError {
         if let Some(error) = Self::new(er) { Err(error) } else { Ok(er) }
     }
 
-    /// Get the raw error code.
+    /// Gets the raw error code.
     #[inline]
     pub fn as_raw(&self) -> abi::ER {
         self.er

library/std/src/sys/pal/itron/task.rs

@@ -5,19 +5,19 @@ use super::{
 
 use crate::mem::MaybeUninit;
 
-/// Get the ID of the task in Running state. Panics on failure.
+/// Gets the ID of the task in Running state. Panics on failure.
 #[inline]
 pub fn current_task_id() -> abi::ID {
     try_current_task_id().unwrap_or_else(|e| fail(e, &"get_tid"))
 }
 
-/// Get the ID of the task in Running state. Aborts on failure.
+/// Gets the ID of the task in Running state. Aborts on failure.
 #[inline]
 pub fn current_task_id_aborting() -> abi::ID {
     try_current_task_id().unwrap_or_else(|e| fail_aborting(e, &"get_tid"))
 }
 
-/// Get the ID of the task in Running state.
+/// Gets the ID of the task in Running state.
 #[inline]
 pub fn try_current_task_id() -> Result<abi::ID, ItronError> {
     unsafe {
@@ -27,13 +27,13 @@ pub fn try_current_task_id() -> Result<abi::ID, ItronError> {
     }
 }
 
-/// Get the specified task's priority. Panics on failure.
+/// Gets the specified task's priority. Panics on failure.
 #[inline]
 pub fn task_priority(task: abi::ID) -> abi::PRI {
     try_task_priority(task).unwrap_or_else(|e| fail(e, &"get_pri"))
 }
 
-/// Get the specified task's priority.
+/// Gets the specified task's priority.
 #[inline]
 pub fn try_task_priority(task: abi::ID) -> Result<abi::PRI, ItronError> {
     unsafe {

library/std/src/sys/pal/itron/thread.rs

@@ -308,7 +308,7 @@ impl Drop for Thread {
     }
 }
 
-/// Terminate and delete the specified task.
+/// Terminates and deletes the specified task.
 ///
 /// This function will abort if `deleted_task` refers to the calling task.
 ///
@@ -337,7 +337,7 @@ unsafe fn terminate_and_delete_task(deleted_task: abi::ID) {
     expect_success_aborting(unsafe { abi::del_tsk(deleted_task) }, &"del_tsk");
 }
 
-/// Terminate and delete the calling task.
+/// Terminates and deletes the calling task.
 ///
 /// Atomicity is not required - i.e., it can be assumed that other threads won't
 /// `ter_tsk` the calling task while this function is still in progress. (This

library/std/src/sys/pal/sgx/abi/usercalls/alloc.rs

@@ -67,7 +67,7 @@ pub unsafe trait UserSafe {
     /// Equivalent to `mem::align_of::<Self>`.
     fn align_of() -> usize;
 
-    /// Construct a pointer to `Self` given a memory range in user space.
+    /// Constructs a pointer to `Self` given a memory range in user space.
     ///
     /// N.B., this takes a size, not a length!
     ///
@@ -77,7 +77,7 @@ pub unsafe trait UserSafe {
     /// correct size and is correctly aligned and points to the right type.
     unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self;
 
-    /// Construct a pointer to `Self` given a memory range.
+    /// Constructs a pointer to `Self` given a memory range.
     ///
     /// N.B., this takes a size, not a length!
     ///
@@ -276,7 +276,7 @@ impl<T> User<T>
 where
     T: UserSafe,
 {
-    /// Allocate space for `T` in user memory.
+    /// Allocates space for `T` in user memory.
     pub fn uninitialized() -> Self {
         Self::new_uninit_bytes(mem::size_of::<T>())
     }
@@ -287,7 +287,7 @@ impl<T> User<[T]>
 where
     [T]: UserSafe,
 {
-    /// Allocate space for a `[T]` of `n` elements in user memory.
+    /// Allocates space for a `[T]` of `n` elements in user memory.
     pub fn uninitialized(n: usize) -> Self {
         Self::new_uninit_bytes(n * mem::size_of::<T>())
     }

library/std/src/sys/pal/sgx/abi/usercalls/mod.rs

@@ -171,10 +171,12 @@ pub fn wait(event_mask: u64, mut timeout: u64) -> IoResult<u64> {
     unsafe { raw::wait(event_mask, timeout).from_sgx_result() }
 }
 
-/// This function makes an effort to wait for a non-spurious event at least as
-/// long as `duration`. Note that in general there is no guarantee about accuracy
-/// of time and timeouts in SGX model. The enclave runner serving usercalls may
-/// lie about current time and/or ignore timeout values.
+/// Makes an effort to wait for a non-spurious event at least as long as
+/// `duration`.
+///
+/// Note that in general there is no guarantee about accuracy of time and
+/// timeouts in SGX model. The enclave runner serving usercalls may lie about
+/// current time and/or ignore timeout values.
 ///
 /// Once the event is observed, `should_wake_up` will be used to determine
 /// whether or not the event was spurious.

library/std/src/sys/pal/uefi/args.rs

@@ -76,7 +76,7 @@ impl DoubleEndedIterator for Args {
 /// This implementation is based on what is defined in Section 3.4 of
 /// [UEFI Shell Specification](https://uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf)
 ///
-/// Return None in the following cases:
+/// Returns None in the following cases:
 /// - Invalid UTF-16 (unpaired surrogate)
 /// - Empty/improper arguments
 fn parse_lp_cmd_line(code_units: &[u16]) -> Option<Vec<OsString>> {

library/std/src/sys/pal/uefi/helpers.rs

@@ -30,8 +30,9 @@ type BootUninstallMultipleProtocolInterfaces =
 const BOOT_SERVICES_UNAVAILABLE: io::Error =
     const_io_error!(io::ErrorKind::Other, "Boot Services are no longer available");
 
-/// Locate Handles with a particular Protocol GUID
-/// Implemented using `EFI_BOOT_SERVICES.LocateHandles()`
+/// Locates Handles with a particular Protocol GUID.
+///
+/// Implemented using `EFI_BOOT_SERVICES.LocateHandles()`.
 ///
 /// Returns an array of [Handles](r_efi::efi::Handle) that support a specified protocol.
 pub(crate) fn locate_handles(mut guid: Guid) -> io::Result<Vec<NonNull<crate::ffi::c_void>>> {
@@ -148,8 +149,9 @@ pub(crate) unsafe fn close_event(evt: NonNull<crate::ffi::c_void>) -> io::Result
     if r.is_error() { Err(crate::io::Error::from_raw_os_error(r.as_usize())) } else { Ok(()) }
 }
 
-/// Get the Protocol for current system handle.
-/// Note: Some protocols need to be manually freed. It is the callers responsibility to do so.
+/// Gets the Protocol for current system handle.
+///
+/// Note: Some protocols need to be manually freed. It is the caller's responsibility to do so.
 pub(crate) fn image_handle_protocol<T>(protocol_guid: Guid) -> io::Result<NonNull<T>> {
     let system_handle = uefi::env::try_image_handle().ok_or(io::const_io_error!(
         io::ErrorKind::NotFound,
@@ -220,7 +222,7 @@ pub(crate) fn device_path_to_text(path: NonNull<device_path::Protocol>) -> io::R
     Err(io::const_io_error!(io::ErrorKind::NotFound, "No device path to text protocol found"))
 }
 
-/// Get RuntimeServices
+/// Gets RuntimeServices.
 pub(crate) fn runtime_services() -> Option<NonNull<r_efi::efi::RuntimeServices>> {
     let system_table: NonNull<r_efi::efi::SystemTable> =
         crate::os::uefi::env::try_system_table()?.cast();

library/std/src/sys/pal/unix/futex.rs

@@ -16,7 +16,7 @@ pub type SmallAtomic = AtomicU32;
 /// Must be the underlying type of SmallAtomic
 pub type SmallPrimitive = u32;
 
-/// Wait for a futex_wake operation to wake us.
+/// Waits for a `futex_wake` operation to wake us.
 ///
 /// Returns directly if the futex doesn't hold the expected value.
 ///
@@ -87,7 +87,7 @@ pub fn futex_wait(futex: &AtomicU32, expected: u32, timeout: Option<Duration>) -
     }
 }
 
-/// Wake up one thread that's blocked on futex_wait on this futex.
+/// Wakes up one thread that's blocked on `futex_wait` on this futex.
 ///
 /// Returns true if this actually woke up such a thread,
 /// or false if no thread was waiting on this futex.
@@ -100,7 +100,7 @@ pub fn futex_wake(futex: &AtomicU32) -> bool {
     unsafe { libc::syscall(libc::SYS_futex, ptr, op, 1) > 0 }
 }
 
-/// Wake up all threads that are waiting on futex_wait on this futex.
+/// Wakes up all threads that are waiting on `futex_wait` on this futex.
 #[cfg(any(target_os = "linux", target_os = "android"))]
 pub fn futex_wake_all(futex: &AtomicU32) {
     let ptr = futex as *const AtomicU32;

library/std/src/sys/pal/unix/mod.rs

@@ -308,7 +308,7 @@ macro_rules! impl_is_minus_one {
 
 impl_is_minus_one! { i8 i16 i32 i64 isize }
 
-/// Convert native return values to Result using the *-1 means error is in `errno`*  convention.
+/// Converts native return values to Result using the *-1 means error is in `errno`*  convention.
 /// Non-error values are `Ok`-wrapped.
 pub fn cvt<T: IsMinusOne>(t: T) -> crate::io::Result<T> {
     if t.is_minus_one() { Err(crate::io::Error::last_os_error()) } else { Ok(t) }

library/std/src/sys/pal/unix/process/process_unix.rs

@@ -1047,7 +1047,7 @@ impl From<c_int> for ExitStatus {
     }
 }
 
-/// Convert a signal number to a readable, searchable name.
+/// Converts a signal number to a readable, searchable name.
 ///
 /// This string should be displayed right after the signal number.
 /// If a signal is unrecognized, it returns the empty string, so that

library/std/src/sys/pal/wasm/atomics/futex.rs

@@ -24,7 +24,7 @@ pub fn futex_wait(futex: &AtomicU32, expected: u32, timeout: Option<Duration>) -
     }
 }
 
-/// Wake up one thread that's blocked on futex_wait on this futex.
+/// Wakes up one thread that's blocked on `futex_wait` on this futex.
 ///
 /// Returns true if this actually woke up such a thread,
 /// or false if no thread was waiting on this futex.
@@ -32,7 +32,7 @@ pub fn futex_wake(futex: &AtomicU32) -> bool {
     unsafe { wasm::memory_atomic_notify(futex as *const AtomicU32 as *mut i32, 1) > 0 }
 }
 
-/// Wake up all threads that are waiting on futex_wait on this futex.
+/// Wakes up all threads that are waiting on `futex_wait` on this futex.
 pub fn futex_wake_all(futex: &AtomicU32) {
     unsafe {
         wasm::memory_atomic_notify(futex as *const AtomicU32 as *mut i32, i32::MAX as u32);

library/std/src/sys/pal/windows/fs.rs

@@ -637,7 +637,7 @@ impl File {
         Ok(())
     }
 
-    /// Get only basic file information such as attributes and file times.
+    /// Gets only basic file information such as attributes and file times.
     fn basic_info(&self) -> io::Result<c::FILE_BASIC_INFO> {
         unsafe {
             let mut info: c::FILE_BASIC_INFO = mem::zeroed();

library/std/src/sys/pal/windows/process.rs

@@ -549,7 +549,7 @@ where
     None
 }
 
-/// Check if a file exists without following symlinks.
+/// Checks if a file exists without following symlinks.
 fn program_exists(path: &Path) -> Option<Vec<u16>> {
     unsafe {
         let path = args::to_user_path(path).ok()?;

library/std/src/sys/pal/windows/time.rs

@@ -230,7 +230,7 @@ pub(super) struct WaitableTimer {
     handle: c::HANDLE,
 }
 impl WaitableTimer {
-    /// Create a high-resolution timer. Will fail before Windows 10, version 1803.
+    /// Creates a high-resolution timer. Will fail before Windows 10, version 1803.
     pub fn high_resolution() -> Result<Self, ()> {
         let handle = unsafe {
             c::CreateWaitableTimerExW(

library/std/src/sys/path/windows.rs

@@ -218,7 +218,7 @@ pub(crate) fn maybe_verbatim(path: &Path) -> io::Result<Vec<u16>> {
     get_long_path(path, true)
 }
 
-/// Get a normalized absolute path that can bypass path length limits.
+/// Gets a normalized absolute path that can bypass path length limits.
 ///
 /// Setting prefer_verbatim to true suggests a stronger preference for verbatim
 /// paths even when not strictly necessary. This allows the Windows API to avoid

library/std/src/sys/personality/dwarf/eh.rs

@@ -170,7 +170,7 @@ fn round_up(unrounded: usize, align: usize) -> Result<usize, ()> {
     if align.is_power_of_two() { Ok((unrounded + align - 1) & !(align - 1)) } else { Err(()) }
 }
 
-/// Read a offset (`usize`) from `reader` whose encoding is described by `encoding`.
+/// Reads an offset (`usize`) from `reader` whose encoding is described by `encoding`.
 ///
 /// `encoding` must be a [DWARF Exception Header Encoding as described by the LSB spec][LSB-dwarf-ext].
 /// In addition the upper ("application") part must be zero.
@@ -202,7 +202,7 @@ unsafe fn read_encoded_offset(reader: &mut DwarfReader, encoding: u8) -> Result<
     Ok(result)
 }
 
-/// Read a pointer from `reader` whose encoding is described by `encoding`.
+/// Reads a pointer from `reader` whose encoding is described by `encoding`.
 ///
 /// `encoding` must be a [DWARF Exception Header Encoding as described by the LSB spec][LSB-dwarf-ext].
 ///

library/std/src/sys/sync/mutex/itron.rs

@@ -13,7 +13,7 @@ pub struct Mutex {
     mtx: SpinIdOnceCell<()>,
 }
 
-/// Create a mutex object. This function never panics.
+/// Creates a mutex object. This function never panics.
 fn new_mtx() -> Result<abi::ID, ItronError> {
     ItronError::err_if_negative(unsafe {
         abi::acre_mtx(&abi::T_CMTX {
@@ -31,7 +31,7 @@ impl Mutex {
         Mutex { mtx: SpinIdOnceCell::new() }
     }
 
-    /// Get the inner mutex's ID, which is lazily created.
+    /// Gets the inner mutex's ID, which is lazily created.
     fn raw(&self) -> abi::ID {
         match self.mtx.get_or_try_init(|| new_mtx().map(|id| (id, ()))) {
             Ok((id, ())) => id,

library/std/src/sys/sync/rwlock/futex.rs

@@ -222,7 +222,7 @@ impl RwLock {
         }
     }
 
-    /// Wake up waiting threads after unlocking.
+    /// Wakes up waiting threads after unlocking.
     ///
     /// If both are waiting, this will wake up only one writer, but will fall
     /// back to waking up readers if there was no writer to wake up.

library/std/src/sys/sync/rwlock/queue.rs

@@ -186,7 +186,7 @@ struct Node {
 }
 
 impl Node {
-    /// Create a new queue node.
+    /// Creates a new queue node.
     fn new(write: bool) -> Node {
         Node {
             next: AtomicLink::new(None),

library/std/src/sys/sync/rwlock/solid.rs

@@ -28,7 +28,7 @@ impl RwLock {
         RwLock { rwl: SpinIdOnceCell::new() }
     }
 
-    /// Get the inner mutex's ID, which is lazily created.
+    /// Gets the inner mutex's ID, which is lazily created.
     fn raw(&self) -> abi::ID {
         match self.rwl.get_or_try_init(|| new_rwl().map(|id| (id, ()))) {
             Ok((id, ())) => id,

library/std/src/sys/sync/thread_parking/futex.rs

@@ -36,7 +36,7 @@ pub struct Parker {
 // Ordering::Release when writing NOTIFIED (the 'token') in unpark(), and using
 // Ordering::Acquire when checking for this state in park().
 impl Parker {
-    /// Construct the futex parker. The UNIX parker implementation
+    /// Constructs the futex parker. The UNIX parker implementation
     /// requires this to happen in-place.
     pub unsafe fn new_in_place(parker: *mut Parker) {
         unsafe { parker.write(Self { state: Atomic::new(EMPTY) }) };

library/std/src/sys/sync/thread_parking/id.rs

@@ -30,7 +30,7 @@ impl Parker {
         Parker { state: AtomicI8::new(EMPTY), tid: UnsafeCell::new(None) }
     }
 
-    /// Create a new thread parker. UNIX requires this to happen in-place.
+    /// Creates a new thread parker. UNIX requires this to happen in-place.
     pub unsafe fn new_in_place(parker: *mut Parker) {
         parker.write(Parker::new())
     }

library/std/src/sys/sync/thread_parking/pthread.rs

@@ -92,7 +92,7 @@ pub struct Parker {
 }
 
 impl Parker {
-    /// Construct the UNIX parker in-place.
+    /// Constructs the UNIX parker in-place.
     ///
     /// # Safety
     /// The constructed parker must never be moved.

library/std/src/sys/sync/thread_parking/windows7.rs

@@ -95,7 +95,7 @@ const NOTIFIED: i8 = 1;
 // Ordering::Release when writing NOTIFIED (the 'token') in unpark(), and using
 // Ordering::Acquire when reading this state in park() after waking up.
 impl Parker {
-    /// Construct the Windows parker. The UNIX parker implementation
+    /// Constructs the Windows parker. The UNIX parker implementation
     /// requires this to happen in-place.
     pub unsafe fn new_in_place(parker: *mut Parker) {
         parker.write(Self { state: AtomicI8::new(EMPTY) });

library/std/src/sys/thread_local/key/xous.rs

@@ -79,7 +79,7 @@ fn tls_ptr_addr() -> *mut *mut u8 {
     core::ptr::with_exposed_provenance_mut::<*mut u8>(tp)
 }
 
-/// Create an area of memory that's unique per thread. This area will
+/// Creates an area of memory that's unique per thread. This area will
 /// contain all thread local pointers.
 fn tls_table() -> &'static mut [*mut u8] {
     let tp = tls_ptr_addr();

library/std/src/sys/thread_local/native/eager.rs

@@ -21,7 +21,7 @@ impl<T> Storage<T> {
         Storage { state: Cell::new(State::Initial), val: UnsafeCell::new(val) }
     }
 
-    /// Get a pointer to the TLS value. If the TLS variable has been destroyed,
+    /// Gets a pointer to the TLS value. If the TLS variable has been destroyed,
     /// a null pointer is returned.
     ///
     /// The resulting pointer may not be used after thread destruction has

library/std/src/sys/thread_local/native/lazy.rs

@@ -39,7 +39,7 @@ where
         Storage { state: UnsafeCell::new(State::Initial) }
     }
 
-    /// Get a pointer to the TLS value, potentially initializing it with the
+    /// Gets a pointer to the TLS value, potentially initializing it with the
     /// provided parameters. If the TLS variable has been destroyed, a null
     /// pointer is returned.
     ///

library/std/src/sys/thread_local/os.rs

@@ -60,7 +60,7 @@ impl<T: 'static> Storage<T> {
         Storage { key: LazyKey::new(Some(destroy_value::<T>)), marker: PhantomData }
     }
 
-    /// Get a pointer to the TLS value, potentially initializing it with the
+    /// Gets a pointer to the TLS value, potentially initializing it with the
     /// provided parameters. If the TLS variable has been destroyed, a null
     /// pointer is returned.
     ///

library/std/src/sys/thread_local/statik.rs

@@ -63,7 +63,7 @@ impl<T> LazyStorage<T> {
         LazyStorage { value: UnsafeCell::new(None) }
     }
 
-    /// Get a pointer to the TLS value, potentially initializing it with the
+    /// Gets a pointer to the TLS value, potentially initializing it with the
     /// provided parameters.
     ///
     /// The resulting pointer may not be used after reentrant inialialization