Update documentation

Author: phil-opp

src/lib.rs

@@ -1,30 +1,14 @@
 #![cfg_attr(feature = "const_fn", feature(const_fn))]
 
-//! Provides wrapper types `Volatile`, `ReadOnly`, `WriteOnly`, `ReadWrite`, which wrap any copy-able type and allows for
-//! volatile memory access to wrapped value. Volatile memory accesses are never optimized away by
-//! the compiler, and are useful in many low-level systems programming and concurrent contexts.
+//! Provides the wrapper type `Volatile`, which wraps a reference to any copy-able type and allows
+//! for volatile memory access to wrapped value. Volatile memory accesses are never optimized away
+//! by the compiler, and are useful in many low-level systems programming and concurrent contexts.
 //!
 //! The wrapper types *do not* enforce any atomicity guarantees; to also get atomicity, consider
 //! looking at the `Atomic` wrapper type found in `libcore` or `libstd`.
 //!
 //! These wrappers do not depend on the standard library and never panic.
-//!
-//! # Dealing with Volatile Pointers
-//!
-//! Frequently, one may have to deal with volatile pointers, eg, writes to specific memory
-//! locations. The canonical way to solve this is to cast the pointer to a volatile wrapper
-//! directly, eg:
-//!
-//! ```rust
-//! use volatile::Volatile;
-//!
-//! let mut_ptr = 0xFEE00000 as *mut u32;
-//!
-//! let volatile_ptr = mut_ptr as *mut Volatile<u32>;
-//! ```
-//!
-//! and then perform operations on the pointer as usual in a volatile way. This method works as all
-//! of the volatile wrapper types are the same size as their contained values.
+
 #![no_std]
 
 pub use crate::access::{ReadWrite, Readable, Writable};
@@ -37,11 +21,14 @@ use core::{
 
 mod access;
 
-/// A wrapper type around a volatile variable, which allows for volatile reads and writes
-/// to the contained value. The stored type needs to be `Copy`, as volatile reads and writes
-/// take and return copies of the value.
+/// A wrapper type around a reference to a volatile variable.
+///
+/// Allows volatile reads and writes on the referenced value. The referenced value needs to
+/// be `Copy`, as volatile reads and writes take and return copies of the value.
 ///
 /// The size of this struct is the same as the size of the contained type.
+///
+/// TODO: read/write permissions
 #[derive(Debug, Default, Clone)]
 #[repr(transparent)]
 pub struct Volatile<T, A = ReadWrite> {
@@ -50,17 +37,18 @@ pub struct Volatile<T, A = ReadWrite> {
 }
 
 impl<T> Volatile<T> {
-    /// Construct a new volatile instance wrapping the given value.
+    /// Construct a new volatile instance wrapping the given value reference.
+    ///
+    /// ## Example
     ///
     /// ```rust
     /// use volatile::Volatile;
     ///
-    /// let value = Volatile::new(0u32);
-    /// ```
-    ///
-    /// # Panics
+    /// let value = 0u32;
     ///
-    /// This method never panics.
+    /// let volatile = Volatile::new(&value);
+    /// assert_eq!(volatile.read(), 0);
+    /// ```
     pub const fn new(value: T) -> Volatile<T> {
         Volatile {
             value,
@@ -70,22 +58,22 @@ impl<T> Volatile<T> {
 }
 
 impl<T: Copy, A> Volatile<&T, A> {
-    /// Performs a volatile read of the contained value, returning a copy
-    /// of the read value. Volatile reads are guaranteed not to be optimized
+    /// Performs a volatile read of the contained value.
+    ///
+    /// Returns a copy of the read value. Volatile reads are guaranteed not to be optimized
     /// away by the compiler, but by themselves do not have atomic ordering
     /// guarantees. To also get atomicity, consider looking at the `Atomic` wrapper type.
     ///
+    /// ## Example
+    ///
     /// ```rust
     /// use volatile::Volatile;
     ///
-    /// let value = Volatile::new(42u32);
+    /// let value = 42;
+    /// let volatile = Volatile::new(&value);
     ///
-    /// assert_eq!(value.read(), 42u32);
+    /// assert_eq!(volatile.read(), 42);
     /// ```
-    ///
-    /// # Panics
-    ///
-    /// This method never panics.
     pub fn read(&self) -> T
     where
         A: Readable,
@@ -96,22 +84,22 @@ impl<T: Copy, A> Volatile<&T, A> {
 }
 
 impl<T: Copy, A> Volatile<&mut T, A> {
-    /// Performs a volatile read of the contained value, returning a copy
-    /// of the read value. Volatile reads are guaranteed not to be optimized
+    /// Performs a volatile read of the contained value.
+    ///
+    /// Returns a copy of the read value. Volatile reads are guaranteed not to be optimized
     /// away by the compiler, but by themselves do not have atomic ordering
     /// guarantees. To also get atomicity, consider looking at the `Atomic` wrapper type.
     ///
+    /// ## Example
+    ///
     /// ```rust
     /// use volatile::Volatile;
     ///
-    /// let value = Volatile::new(42u32);
+    /// let mut value = 42;
+    /// let volatile = Volatile::new(&mut value);
     ///
-    /// assert_eq!(value.read(), 42u32);
+    /// assert_eq!(volatile.read(), 42);
     /// ```
-    ///
-    /// # Panics
-    ///
-    /// This method never panics.
     pub fn read(&self) -> T
     where
         A: Readable,
@@ -120,24 +108,23 @@ impl<T: Copy, A> Volatile<&mut T, A> {
         unsafe { ptr::read_volatile(self.value) }
     }
 
-    /// Performs a volatile write, setting the contained value to the given value `value`. Volatile
-    /// writes are guaranteed to not be optimized away by the compiler, but by themselves do not
-    /// have atomic ordering guarantees. To also get atomicity, consider looking at the `Atomic`
-    /// wrapper type.
+    /// Performs a volatile write, setting the contained value to the given `value`.
+    ///
+    /// Volatile writes are guaranteed to not be optimized away by the compiler, but by
+    /// themselves do not have atomic ordering guarantees. To also get atomicity, consider
+    /// looking at the `Atomic` wrapper type.
+    ///
+    /// ## Example
     ///
     /// ```rust
     /// use volatile::Volatile;
     ///
-    /// let mut value = Volatile::new(0u32);
+    /// let mut value = 42;
+    /// let mut volatile = Volatile::new(&mut value);
+    /// volatile.write(50);
     ///
-    /// value.write(42u32);
-    ///
-    /// assert_eq!(value.read(), 42u32);
+    /// assert_eq!(volatile.read(), 50);
     /// ```
-    ///
-    /// # Panics
-    ///
-    /// This method never panics.
     pub fn write(&mut self, value: T)
     where
         A: Writable,
@@ -146,23 +133,21 @@ impl<T: Copy, A> Volatile<&mut T, A> {
         unsafe { ptr::write_volatile(self.value, value) };
     }
 
+    /// Updates the contained value using the given closure and volatile instructions.
+    ///
     /// Performs a volatile read of the contained value, passes a mutable reference to it to the
     /// function `f`, and then performs a volatile write of the (potentially updated) value back to
     /// the contained value.
     ///
     /// ```rust
     /// use volatile::Volatile;
     ///
-    /// let mut value = Volatile::new(21u32);
+    /// let mut value = 42;
+    /// let mut volatile = Volatile::new(&mut value);
+    /// volatile.update(|val| *val += 1);
     ///
-    /// value.update(|val_ref| *val_ref *= 2);
-    ///
-    /// assert_eq!(value.read(), 42u32);
+    /// assert_eq!(volatile.read(), 43);
     /// ```
-    ///
-    /// # Panics
-    ///
-    /// Ths method never panics.
     pub fn update<F>(&mut self, f: F)
     where
         F: FnOnce(&mut T),