Fix bad indentation in Markdown around lists

Some doc comments were being incorrectly interpreted due to missing
indentation (for intentional line contintuations) or line breaks (for
new lines that were intended to be separate paragraphs).

Clippy warns about these as of Rust 1.80:
<https://rust-lang.github.io/rust-clippy/master/index.html#/doc_lazy_continuation>

Fix them along with some other nearby minor formatting cleanups.

TEST=tools/cargo-doc
TEST=tools/clippy # with rust-toolchain 1.80

Change-Id: Ice0b7cc3bd75d9ab08c10107a13f95ca9f87a0a3
Reviewed-on: https://chromium-review.googlesource.com/c/crosvm/crosvm/+/5758934
Auto-Submit: Daniel Verkamp <dverkamp@chromium.org>
Reviewed-by: Frederick Mayle <fmayle@google.com>
Commit-Queue: Daniel Verkamp <dverkamp@chromium.org>

base/src/volatile_memory.rs

@@ -14,7 +14,8 @@
 //! For the purposes of maintaining safety, volatile memory has some rules of its own:
 //! 1. No references or slices to volatile memory (`&` or `&mut`).
 //! 2. Access should always been done with a volatile read or write.
-//! The First rule is because having references of any kind to memory considered volatile would
+//!
+//! The first rule is because having references of any kind to memory considered volatile would
 //! violate pointer aliasing. The second is because unvolatile accesses are inherently undefined if
 //! done concurrently without synchronization. With volatile access we know that the compiler has
 //! not reordered or elided the access.

cros_async/src/sys/linux/uring_executor.rs

@@ -10,7 +10,7 @@
 //!
 //! There are two key issues managing asynchronous IO buffers in rust.
 //! 1) The kernel has a mutable reference to the memory until the completion is returned. Rust must
-//! not have any references to it during that time.
+//!    not have any references to it during that time.
 //! 2) The memory must remain valid as long as the kernel has a reference to it.
 //!
 //! ### The kernel's mutable borrow of the buffer

devices/src/acpi.rs

@@ -361,43 +361,43 @@ pub const ACPIPM_GPE_MAX: u16 = ACPIPM_RESOURCE_GPE0_BLK_LEN as u16 / 2 * 8 - 1;
 
 /// ACPI PM register value definitions
 
-/// 4.8.4.1.1 PM1 Status Registers, ACPI Spec Version 6.4
+/// Section 4.8.4.1.1 PM1 Status Registers, ACPI Spec Version 6.4
 /// Register Location: <PM1a_EVT_BLK / PM1b_EVT_BLK> System I/O or Memory Space (defined in FADT)
 /// Size: PM1_EVT_LEN / 2 (defined in FADT)
 const PM1_STATUS: u16 = 0;
 
-/// 4.8.4.1.2 PM1Enable Registers, ACPI Spec Version 6.4
+/// Section 4.8.4.1.2 PM1Enable Registers, ACPI Spec Version 6.4
 /// Register Location: <<PM1a_EVT_BLK / PM1b_EVT_BLK> + PM1_EVT_LEN / 2 System I/O or Memory Space
 /// (defined in FADT)
 /// Size: PM1_EVT_LEN / 2 (defined in FADT)
 const PM1_ENABLE: u16 = PM1_STATUS + (ACPIPM_RESOURCE_EVENTBLK_LEN as u16 / 2);
 
-/// 4.8.4.2.1 PM1 Control Registers, ACPI Spec Version 6.4
+/// Section 4.8.4.2.1 PM1 Control Registers, ACPI Spec Version 6.4
 /// Register Location: <PM1a_CNT_BLK / PM1b_CNT_BLK> System I/O or Memory Space (defined in FADT)
 /// Size: PM1_CNT_LEN (defined in FADT)
 const PM1_CONTROL: u16 = PM1_STATUS + ACPIPM_RESOURCE_EVENTBLK_LEN as u16;
 
-/// 4.8.5.1 General-Purpose Event Register Blocks, ACPI Spec Version 6.4
+/// Section 4.8.5.1 General-Purpose Event Register Blocks, ACPI Spec Version 6.4
 /// - Each register block contains two registers: an enable and a status register.
 /// - Each register block is 32-bit aligned.
 /// - Each register in the block is accessed as a byte.
-
-/// 4.8.5.1.1 General-Purpose Event 0 Register Block, ACPI Spec Version 6.4
+///
+/// Section 4.8.5.1.1 General-Purpose Event 0 Register Block, ACPI Spec Version 6.4
 /// This register block consists of two registers: The GPE0_STS and the GPE0_EN registers. Each
 /// register’s length is defined to be half the length of the GPE0 register block, and is described
 /// in the ACPI FADT’s GPE0_BLK and GPE0_BLK_LEN operators.
-
-/// 4.8.5.1.1.1 General-Purpose Event 0 Status Register, ACPI Spec Version 6.4
+///
+/// Section 4.8.5.1.1.1 General-Purpose Event 0 Status Register, ACPI Spec Version 6.4
 /// Register Location: <GPE0_STS> System I/O or System Memory Space (defined in FADT)
 /// Size: GPE0_BLK_LEN/2 (defined in FADT)
 const GPE0_STATUS: u16 = PM1_STATUS + ACPIPM_RESOURCE_EVENTBLK_LEN as u16 + 4; // ensure alignment
 
-/// 4.8.5.1.1.2 General-Purpose Event 0 Enable Register, ACPI Spec Version 6.4
+/// Section 4.8.5.1.1.2 General-Purpose Event 0 Enable Register, ACPI Spec Version 6.4
 /// Register Location: <GPE0_EN> System I/O or System Memory Space (defined in FADT)
 /// Size: GPE0_BLK_LEN/2 (defined in FADT)
 const GPE0_ENABLE: u16 = GPE0_STATUS + (ACPIPM_RESOURCE_GPE0_BLK_LEN as u16 / 2);
 
-/// 4.8.4.1.1, 4.8.4.1.2 Fixed event bits in both PM1 Status and PM1 Enable registers.
+/// Section 4.8.4.1.1, 4.8.4.1.2 Fixed event bits in both PM1 Status and PM1 Enable registers.
 const BITSHIFT_PM1_GBL: u16 = 5;
 const BITSHIFT_PM1_PWRBTN: u16 = 8;
 const BITSHIFT_PM1_SLPBTN: u16 = 9;

devices/src/virtio/video/worker.rs

@@ -292,8 +292,7 @@ impl Worker {
     ///
     /// * `device` - Instance of backend device
     /// * `stream_id` - Stream session ID of the event
-    /// * `wait_ctx` - `device` may deregister the completed `Token::BufferBarrier` from
-    /// `wait_ctx`.
+    /// * `wait_ctx` - `device` may deregister the completed `Token::BufferBarrier` from `wait_ctx`.
     fn handle_buffer_barrier(
         &mut self,
         device: &mut dyn Device,

devices/src/virtio/virtio_pci_common_config.rs

@@ -15,24 +15,24 @@ use super::*;
 /// device.
 ///
 /// * Registers:
-/// ** About the whole device.
-/// le32 device_feature_select;     // read-write
-/// le32 device_feature;            // read-only for driver
-/// le32 driver_feature_select;     // read-write
-/// le32 driver_feature;            // read-write
-/// le16 msix_config;               // read-write
-/// le16 num_queues;                // read-only for driver
-/// u8 device_status;               // read-write (driver_status)
-/// u8 config_generation;           // read-only for driver
-/// ** About a specific virtqueue.
-/// le16 queue_select;              // read-write
-/// le16 queue_size;                // read-write, power of 2, or 0.
-/// le16 queue_msix_vector;         // read-write
-/// le16 queue_enable;              // read-write (Ready)
-/// le16 queue_notify_off;          // read-only for driver
-/// le64 queue_desc;                // read-write
-/// le64 queue_avail;               // read-write
-/// le64 queue_used;                // read-write
+///   * About the whole device.
+///     * le32 device_feature_select;     // read-write
+///     * le32 device_feature;            // read-only for driver
+///     * le32 driver_feature_select;     // read-write
+///     * le32 driver_feature;            // read-write
+///     * le16 msix_config;               // read-write
+///     * le16 num_queues;                // read-only for driver
+///     * u8 device_status;               // read-write (driver_status)
+///     * u8 config_generation;           // read-only for driver
+///   * About a specific virtqueue.
+///     * le16 queue_select;              // read-write
+///     * le16 queue_size;                // read-write, power of 2, or 0.
+///     * le16 queue_msix_vector;         // read-write
+///     * le16 queue_enable;              // read-write (Ready)
+///     * le16 queue_notify_off;          // read-only for driver
+///     * le64 queue_desc;                // read-write
+///     * le64 queue_avail;               // read-write
+///     * le64 queue_used;                // read-write
 #[derive(Copy, Clone, Serialize, Deserialize)]
 pub struct VirtioPciCommonConfig {
     pub driver_status: u8,

fuse/src/filesystem.rs

@@ -1271,8 +1271,8 @@ pub trait FileSystem {
     ///
     /// b) File exist already (exception is O_EXCL)
     ///    - O_CREAT:
-    ///     - Open the file
-    ///     - Return d_entry and file handler
+    ///      - Open the file
+    ///      - Return d_entry and file handler
     ///    - O_EXCL:
     ///      - EEXIST
     ///

fuse/src/server.rs

@@ -1940,18 +1940,18 @@ fn add_dirent<W: Writer>(
 /// # Arguments
 ///
 /// * `buf` - a byte array that contains the contents following any expected byte string parameters
-/// of the FUSE request from the server. It begins with a struct `SecctxHeader`, and then the
-/// subsequent entry is a struct `Secctx` followed by a nul-terminated string with the xattribute
-/// name and then another nul-terminated string with the value for that xattr.
+///   of the FUSE request from the server. It begins with a struct `SecctxHeader`, and then the
+///   subsequent entry is a struct `Secctx` followed by a nul-terminated string with the xattribute
+///   name and then another nul-terminated string with the value for that xattr.
 ///
 /// # Errors
 ///
 /// * `Error::InvalidHeaderLength` - indicates that there is an inconsistency between the size of
-/// the data read from `buf` and the stated `size` of the `SecctxHeader`, the respective `Secctx`
-/// struct, or `buf` itself.
+///   the data read from `buf` and the stated `size` of the `SecctxHeader`, the respective `Secctx`
+///   struct, or `buf` itself.
 /// * `Error::DecodeMessage` - indicates that the expected structs cannot be read from `buf`.
 /// * `Error::MissingParameter` - indicates that either a security context `name` or `value` is
-/// missing from a security context entry.
+///   missing from a security context entry.
 fn parse_selinux_xattr(buf: &[u8]) -> Result<Option<&CStr>> {
     // Return early if request was not followed by context information
     if buf.is_empty() {

gpu_display/src/dwl.rs

@@ -11,6 +11,7 @@
 /// - @subpage page_iface_zxdg_surface_v6 - desktop user interface surface base interface
 /// - @subpage page_iface_zxdg_toplevel_v6 - toplevel surface
 /// - @subpage page_iface_zxdg_popup_v6 - short-lived, popup surfaces for menus
+///
 /// @section page_copyright_xdg_shell_unstable_v6 Copyright
 /// <pre>
 ///

hypervisor/src/x86_64.rs

@@ -186,9 +186,9 @@ pub trait VcpuX86_64: Vcpu {
     ///
     /// It sets TSC_OFFSET (VMCS / CB field) by setting the TSC MSR to the current
     /// host TSC value plus the desired offset. We rely on the fact that hypervisors
-    /// determine the value of TSC_OFFSET by computing TSC_OFFSET = new_tsc_value
-    /// - _rdtsc() = _rdtsc() + offset - _rdtsc() ~= offset. Note that the ~= is
-    /// important: this is an approximate operation, because the two _rdtsc() calls
+    /// determine the value of TSC_OFFSET by computing TSC_OFFSET = `new_tsc_value - _rdtsc()` =
+    /// `_rdtsc() + offset - _rdtsc()` ~= `offset`. Note that the ~= is important: this is an
+    /// approximate operation, because the two _rdtsc() calls
     /// are separated by at least a few ticks.
     ///
     /// Note: TSC_OFFSET, host TSC, guest TSC, and TSC MSR are all different

third_party/vmm_vhost/src/backend_server.rs

@@ -357,12 +357,12 @@ impl<S: Backend> BackendServer<S> {
     /// See [`BackendServer::recv_header`]'s doc comment for the usage.
     ///
     /// # Return:
-    /// * - `Ok(())`: one request was successfully handled.
-    /// * - `Err(ClientExit)`: the frontend closed the connection properly. This isn't an actual
+    /// * `Ok(())`: one request was successfully handled.
+    /// * `Err(ClientExit)`: the frontend closed the connection properly. This isn't an actual
     ///   failure.
-    /// * - `Err(Disconnect)`: the connection was closed unexpectedly.
-    /// * - `Err(InvalidMessage)`: the vmm sent a illegal message.
-    /// * - other errors: failed to handle a request.
+    /// * `Err(Disconnect)`: the connection was closed unexpectedly.
+    /// * `Err(InvalidMessage)`: the vmm sent a illegal message.
+    /// * other errors: failed to handle a request.
     pub fn process_message(
         &mut self,
         hdr: VhostUserMsgHeader<FrontendReq>,

third_party/vmm_vhost/src/sys/unix.rs

@@ -224,6 +224,7 @@ impl SocketPlatformConnection {
     /// attached file descriptors, the receiver must obey following rules:
     ///   1) file descriptors are attached to a message.
     ///   2) message(packet) boundaries must be respected on the receive side.
+    ///
     /// In other words, recvmsg() operations must not cross the packet boundary, otherwise the
     /// attached file descriptors will get lost.
     /// Note that this function wraps received file descriptors as `File`.

x86_64/src/lib.rs

@@ -1507,9 +1507,9 @@ impl X8664arch {
     /// Sets up fw_cfg device.
     ///  # Arguments
     ///
-    /// * - `io_bus` - the IO bus object
-    /// * - `fw_cfg_parameters` - command-line specified data to add to device. May contain
-    /// all None fields if user did not specify data to add to the device
+    /// * `io_bus` - the IO bus object
+    /// * `fw_cfg_parameters` - command-line specified data to add to device. May contain all None
+    ///   fields if user did not specify data to add to the device
     fn setup_fw_cfg_device(
         io_bus: &Bus,
         fw_cfg_parameters: Vec<FwCfgParameters>,
@@ -1652,15 +1652,15 @@ impl X8664arch {
     ///
     /// # Arguments
     ///
-    /// * - `io_bus` the I/O bus to add the devices to
-    /// * - `resources` the SystemAllocator to allocate IO and MMIO for acpi devices.
-    /// * - `suspend_tube` the tube object which used to suspend/resume the VM.
-    /// * - `sdts` ACPI system description tables
-    /// * - `irq_chip` the IrqChip object for registering irq events
-    /// * - `battery` indicate whether to create the battery
-    /// * - `mmio_bus` the MMIO bus to add the devices to
-    /// * - `pci_irqs` IRQ assignment of PCI devices. Tuples of (PCI address, gsi, PCI interrupt
-    ///   pin). Note that this matches one of the return values of generate_pci_root.
+    /// * `io_bus` the I/O bus to add the devices to
+    /// * `resources` the SystemAllocator to allocate IO and MMIO for acpi devices.
+    /// * `suspend_tube` the tube object which used to suspend/resume the VM.
+    /// * `sdts` ACPI system description tables
+    /// * `irq_chip` the IrqChip object for registering irq events
+    /// * `battery` indicate whether to create the battery
+    /// * `mmio_bus` the MMIO bus to add the devices to
+    /// * `pci_irqs` IRQ assignment of PCI devices. Tuples of (PCI address, gsi, PCI interrupt pin).
+    ///   Note that this matches one of the return values of generate_pci_root.
     pub fn setup_acpi_devices(
         pci_root: Arc<Mutex<PciRoot>>,
         mem: &GuestMemory,