Merge pull request #1759 from rust-osdev/doc-improv

style: cargo doc fixes and improvements

Author: nicholasbishop

uefi/src/boot.rs

@@ -531,7 +531,9 @@ pub fn check_event(event: Event) -> Result<bool> {
     }
 }
 
-/// Places the supplied `event` in the signaled state. If `event` is already in
+/// Places the supplied `event` in the signaled state.
+///
+/// If `event` is already in
 /// the signaled state, the function returns successfully. If `event` is of type
 /// [`NOTIFY_SIGNAL`], the event's notification function is scheduled to be
 /// invoked at the event's notification task priority level.
@@ -746,12 +748,14 @@ pub unsafe fn install_protocol_interface(
     .to_result_with_val(|| unsafe { Handle::from_ptr(handle) }.unwrap())
 }
 
-/// Reinstalls a protocol interface on a device handle. `old_interface` is replaced with `new_interface`.
-/// These interfaces may be the same, in which case the registered protocol notifications occur for the handle
-/// without replacing the interface.
+/// Reinstalls a protocol interface on a device handle. `old_interface` is
+/// replaced with `new_interface`.
+///
+/// These interfaces may be the same, in which case the registered protocol
+/// notifications occur for the handle without replacing the interface.
 ///
-/// As with `install_protocol_interface`, any process that has registered to wait for the installation of
-/// the interface is notified.
+/// As with `install_protocol_interface`, any process that has registered to
+/// wait for the installation of the interface is notified.
 ///
 /// # Safety
 ///

uefi/src/data_types/strs.rs

@@ -770,6 +770,7 @@ impl UnalignedSlice<'_, u16> {
 }
 
 /// The EqStrUntilNul trait helps to compare Rust strings against UEFI string types (UCS-2 strings).
+///
 /// The given generic implementation of this trait enables us that we only have to
 /// implement one direction (`left.eq_str_until_nul(&right)`) for each UEFI string type and we
 /// get the other direction (`right.eq_str_until_nul(&left)`) for free. Hence, the relation is

uefi/src/mem/memory_map/mod.rs

@@ -60,7 +60,9 @@ impl Align for MemoryDescriptor {
 pub struct MemoryMapKey(pub(crate) usize);
 
 /// A structure containing the meta attributes associated with a call to
-/// `GetMemoryMap` of UEFI. Note that all values refer to the time this was
+/// `GetMemoryMap` of UEFI.
+///
+/// Note that all values refer to the time this was
 /// called. All following invocations (hidden, subtle, and asynchronous ones)
 /// will likely invalidate this.
 #[derive(Copy, Clone, Debug)]

uefi/src/proto/media/file/mod.rs

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! This module provides the `FileHandle` structure as well as the more specific `RegularFile` and
-//! `Directory` structures. This module also provides the `File` trait for opening, querying,
+//! This module provides the [`FileHandle`] structure as well as the more
+//! specific [`RegularFile`] and [`Directory`] structures.
+//!
+//! This module also provides the [`File`] trait for opening, querying,
 //! creating, reading, and writing files.
 //!
 //! Usually a file system implementation will return a "root" directory, representing

uefi/src/runtime.rs

@@ -514,7 +514,9 @@ pub fn reset(reset_type: ResetType, status: Status, data: Option<&[u8]>) -> ! {
 }
 
 /// Changes the runtime addressing mode of EFI firmware from physical to
-/// virtual. It is up to the caller to translate the old system table address
+/// virtual.
+///
+/// It is up to the caller to translate the old system table address
 /// to a new virtual address and provide it for this function.
 ///
 /// If successful, this function will call [`set_system_table`] with
@@ -906,9 +908,10 @@ impl Display for VariableKey {
 }
 
 /// Information about UEFI variable storage space returned by
-/// [`query_variable_info`]. Note that the data here is
-/// limited to a specific type of variable (as specified by the
-/// `attributes` argument to `query_variable_info`).
+/// [`query_variable_info`].
+///
+/// Note that the data here is limited to a specific type of variable (as
+/// specified by the `attributes` argument to `query_variable_info`).
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct VariableStorageInfo {
     /// Maximum size in bytes of the storage space available for