ISSUE-67 - Enable doc_markdown clippy

* Enable doc_markdown clippy
* Make clippy recommended changes to existing docs

Fixes: #67
Signed-off-by: joshmc <[email protected]>

Author: jmcconnell26

src/address.rs

@@ -11,8 +11,8 @@
 //! Traits to represent an address within an address space.
 //!
 //! Two traits are defined to represent an address within an address space:
-//! - [AddressValue](trait.AddressValue.html): stores the raw value of an address. Typically `u32`,
-//! `u64` or `usize` is used to store the raw value. But pointers, such as `*u8`, can't be used
+//! - [`AddressValue`](trait.AddressValue.html): stores the raw value of an address. Typically
+//! `u32`,`u64` or `usize` is used to store the raw value. But pointers, such as `*u8`, can't be used
 //! because they don't implement the [`Add`](https://doc.rust-lang.org/std/ops/trait.Add.html) and
 //! [`Sub`](https://doc.rust-lang.org/std/ops/trait.Sub.html) traits.
 //! - [Address](trait.Address.html): encapsulates an [`AddressValue`](trait.AddressValue.html)
@@ -51,15 +51,15 @@ pub trait AddressValue {
 
 /// Trait to represent an address within an address space.
 ///
-/// To simplify the design and implementation, assume the same raw data type (AddressValue::V)
-/// could be used to store address, size and offset for the address space. Thus the Address trait
+/// To simplify the design and implementation, assume the same raw data type `(AddressValue::V)`
+/// could be used to store address, size and offset for the address space. Thus the `Address` trait
 /// could be used to manage address, size and offset. On the other hand, type aliases may be
 /// defined to improve code readability.
 ///
-/// One design rule is applied to the Address trait, namely that operators (+, -, &, | etc) are not
-/// supported and it forces clients to explicitly invoke corresponding methods. But there are
+/// One design rule is applied to the `Address` trait, namely that operators (+, -, &, | etc) are
+/// not supported and it forces clients to explicitly invoke corresponding methods. But there are
 /// always exceptions:
-///     Address (BitAnd|BitOr) AddressValue are supported.
+///     `Address` (BitAnd|BitOr) `AddressValue` are supported.
 pub trait Address:
     AddressValue
     + Sized

src/bytes.rs

@@ -8,7 +8,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
 
-//! Define the ByteValued trait to mark that it is safe to instantiate the struct with random data.
+//! Define the `ByteValued` trait to mark that it is safe to instantiate the struct with random
+//! data.
 
 use crate::VolatileSlice;
 use std::io::{Read, Write};
@@ -102,12 +103,12 @@ pub unsafe trait ByteValued: Copy + Default + Send + Sync {
         unsafe { from_raw_parts_mut(self as *mut Self as *mut u8, size_of::<Self>()) }
     }
 
-    /// Converts a mutable reference to `self` into a VolatileSlice.  This is
+    /// Converts a mutable reference to `self` into a `VolatileSlice`.  This is
     /// useful because `VolatileSlice` provides a `Bytes<usize>` implementation.
     ///
     /// # Safety
     ///
-    /// Unlike most VolatileMemory implementation, this method requires an exclusive
+    /// Unlike most `VolatileMemory` implementation, this method requires an exclusive
     /// reference to `self`; this trivially fulfills `VolatileSlice::new`'s requirement
     /// that all accesses to `self` use volatile accesses (because there can
     /// be no other accesses).

src/guest_memory.rs

@@ -17,19 +17,21 @@
 //! a hypervisor).
 //!
 //! Traits and Structs
-//! - [GuestAddress](struct.GuestAddress.html): represents a guest physical address (GPA).
-//! - [MemoryRegionAddress](struct.MemoryRegionAddress.html): represents an offset inside a region.
-//! - [GuestMemoryRegion](trait.GuestMemoryRegion.html): represent a continuous region of guest's
+//! - [`GuestAddress`](struct.GuestAddress.html): represents a guest physical address (GPA).
+//! - [`MemoryRegionAddress`](struct.MemoryRegionAddress.html): represents an offset inside a
+//! region.
+//! - [`GuestMemoryRegion`](trait.GuestMemoryRegion.html): represent a continuous region of guest's
 //! physical memory.
-//! - [GuestMemory](trait.GuestMemory.html): represent a collection of GuestMemoryRegion objects.
-//! The main responsibilities of the GuestMemory trait are:
+//! - [`GuestMemory`](trait.GuestMemory.html): represent a collection of `GuestMemoryRegion`
+//! objects.
+//! The main responsibilities of the `GuestMemory` trait are:
 //!     - hide the detail of accessing guest's physical address.
-//!     - map a request address to a GuestMemoryRegion object and relay the request to it.
-//!     - handle cases where an access request spanning two or more GuestMemoryRegion objects.
+//!     - map a request address to a `GuestMemoryRegion` object and relay the request to it.
+//!     - handle cases where an access request spanning two or more `GuestMemoryRegion` objects.
 //!
-//! Whenever a collection of GuestMemoryRegion objects is mutable,
-//! [GuestAddressSpace](trait.GuestAddressSpace.html) should be implemented
-//! for clients to obtain a [GuestMemory] reference or smart pointer.
+//! Whenever a collection of `GuestMemoryRegion` objects is mutable,
+//! [`GuestAddressSpace`](trait.GuestAddressSpace.html) should be implemented
+//! for clients to obtain a [`GuestMemory`] reference or smart pointer.
 
 use std::convert::From;
 use std::fmt::{self, Display};
@@ -122,7 +124,7 @@ impl_address_ops!(GuestAddress, u64);
 pub struct MemoryRegionAddress(pub u64);
 impl_address_ops!(MemoryRegionAddress, u64);
 
-/// Type of the raw value stored in a GuestAddress object.
+/// Type of the raw value stored in a `GuestAddress` object.
 pub type GuestUsize = <GuestAddress as AddressValue>::V;
 
 /// Represents the start point within a `File` that backs a `GuestMemoryRegion`.
@@ -287,15 +289,15 @@ pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
     }
 }
 
-/// GuestAddressSpace provides a way to retrieve a GuestMemory object.
+/// `GuestAddressSpace` provides a way to retrieve a `GuestMemory` object.
 /// The vm-memory crate already provides trivial implementation for
-/// references to GuestMemory or reference-counted GuestMemory objects,
+/// references to `GuestMemory` or reference-counted `GuestMemory` objects,
 /// but the trait can also be implemented by any other struct in order
 /// to provide temporary access to a snapshot of the memory map.
 ///
 /// In order to support generic mutable memory maps, devices (or other things
-/// that access memory) should store the memory as a GuestAddressSpace<M>.
-/// This example shows that references can also be used as the GuestAddressSpace
+/// that access memory) should store the memory as a `GuestAddressSpace<M>`.
+/// This example shows that references can also be used as the `GuestAddressSpace`
 /// implementation, providing a zero-cost abstraction whenever immutable memory
 /// maps are sufficient.
 ///
@@ -391,15 +393,15 @@ impl<M: GuestMemory> GuestAddressSpace for Arc<M> {
     }
 }
 
-/// GuestMemory represents a container for an *immutable* collection of
-/// GuestMemoryRegion objects.  GuestMemory provides the `Bytes<GuestAddress>`
+/// `GuestMemory` represents a container for an *immutable* collection of
+/// `GuestMemoryRegion` objects.  `GuestMemory` provides the `Bytes<GuestAddress>`
 /// trait to hide the details of accessing guest memory by physical address.
-/// Interior mutability is not allowed for implementations of GuestMemory so
+/// Interior mutability is not allowed for implementations of `GuestMemory` so
 /// that they always provide a consistent view of the memory map.
 ///
-/// The task of the GuestMemory trait are:
-/// - map a request address to a GuestMemoryRegion object and relay the request to it.
-/// - handle cases where an access request spanning two or more GuestMemoryRegion objects.
+/// The task of the `GuestMemory` trait are:
+/// - map a request address to a `GuestMemoryRegion` object and relay the request to it.
+/// - handle cases where an access request spanning two or more `GuestMemoryRegion` objects.
 pub trait GuestMemory {
     /// Type of objects hosted by the address space.
     type R: GuestMemoryRegion;

src/lib.rs

@@ -16,6 +16,7 @@
 //! components, such as boot loader, virtual device drivers, virtio backend drivers and vhost
 //! drivers etc, could be shared and reused by multiple hypervisors.
 
+#![deny(clippy::doc_markdown)]
 #![deny(missing_docs)]
 
 #[macro_use]

src/volatile_memory.rs

@@ -518,7 +518,7 @@ impl Bytes<usize> for VolatileSlice<'_> {
     type E = Error;
 
     /// # Examples
-    /// * Write a slice of size 5 at offset 1020 of a 1024-byte VolatileSlice.
+    /// * Write a slice of size 5 at offset 1020 of a 1024-byte `VolatileSlice`.
     ///
     /// ```
     /// #   use vm_memory::{Bytes, VolatileMemory};
@@ -542,7 +542,7 @@ impl Bytes<usize> for VolatileSlice<'_> {
     }
 
     /// # Examples
-    /// * Read a slice of size 16 at offset 1010 of a 1024-byte VolatileSlice.
+    /// * Read a slice of size 16 at offset 1010 of a 1024-byte `VolatileSlice`.
     ///
     /// ```
     /// #   use vm_memory::{Bytes, VolatileMemory};