Doc update (#8)

* Doc update and fixes

* Misc doc fixes and changes

Author: vchlin

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "clone_cell"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2018"
 authors = ["Vektorlynk"]
 license = "MIT OR Apache-2.0"

README.md

@@ -1,9 +1,9 @@
 # clone_cell
 
-clone_cell provides a `Cell` implementation that works with types whose `Clone` implementations are
+clone_cell provides a `Cell` implementation that works with types whose `clone` methods are
 guaranteed not to mutate the `Cell` content through the `&self` reference. This is enforced with the
 provided `PureClone` trait, which is a subtrait of `Clone` (and a logical supertrait of `Copy`). It
-is only implemented for types with compliant `clone` methods.
+is only implemented for types with a compliant `clone` method.
 
 ## Overview
 
@@ -82,12 +82,14 @@ See the [`clone`] module documentation for more information.
 - Similar to `std::cell::Cell`, this `Cell` is `!Sync`.
 - Since a new trait `PureClone` is used, there is no out-of-the-box support for types from third-party crates.
 
-## Soundness
+## Safety
 
-I believe this is sound, because `PureClone` is unsafe to implement. This trait is implemented for:
+This is safe to use, because `PureClone` is an `unsafe` trait, and all `PureClone` implementations
+are checked. This trait is implemented for:
 - `Copy` types;
 - Types that perform a shallow clone such as `Rc` and `Weak`; and
-- Types whose `clone` methods are otherwise known to be safe, such as compound types that only contain `PureClone` types.
+- Types whose `clone` methods are otherwise known to be safe, such as compound types that only
+  contain `PureClone` types.
 
 See the [documentation] for more information. Please let me know if you find any soundness issues!
 

src/cell.rs

@@ -2,17 +2,14 @@
 //!
 //! # When to use `Cell`
 //!
-//! [`Cell::get`] only requires `T` to be [`PureClone`]. This is useful when working
-//! with with shared `struct`s whose fields are of types `Rc<T>`, `Weak<T>`,
-//! `Option<T: PureClone>`, etc.
+//! [`Cell::get`] only requires `T` to be [`PureClone`](crate::clone::PureClone). This is useful
+//! when working with with shared `struct`s whose fields are of types `Rc<T>`, `Weak<T>`, `Option<T:
+//! PureClone>`, etc.
 //!
-//! Note that just because there can be any number of readers and writers to a
-//! [`Cell`] does not mean it is always a good pattern. In most cases, it may not
-//! make sense to have more than one writer at a time. But the user can easily build
-//! zero-cost abstractions on top of a `Cell` to enforce this. For example, this may be
-//! useful when implementing the observer pattern.
-//!
-//! [`PureClone`]: crate::clone::PureClone
+//! Note that just because there can be any number of readers and writers to a [`Cell`] does not
+//! mean it is always a good pattern. In most cases, it may not make sense to have more than one
+//! writer at a time. But the user can easily build zero-cost abstractions on top of a `Cell` to
+//! enforce this. For example, this may be useful when implementing the observer pattern.
 
 use core::{
     cell::UnsafeCell,
@@ -24,11 +21,8 @@ use core::{
 
 use crate::clone::PureClone;
 
-/// A mutable memory location with a [`get`] method that works with [`PureClone`]
-/// types.
-///
-/// [`PureClone`]: crate::clone::PureClone
-/// [`get`]: Cell::get
+/// A mutable memory location with a [`get`](Cell::get) method that works with
+/// [`PureClone`](crate::clone::PureClone) types.
 ///
 /// # Examples
 ///
@@ -86,8 +80,8 @@ impl<T> Cell<T> {
         drop(old);
     }
 
-    /// Swaps the values of two `Cell`s. Unlike `std::mem::swap`, this does not
-    /// require a `&mut` reference.
+    /// Swaps the values of two `Cell`s. Unlike `std::mem::swap`, this does not require a `&mut`
+    /// reference.
     ///
     /// # Examples
     ///
@@ -213,8 +207,8 @@ where
         self.value.get()
     }
 
-    /// Returns a mutable reference to the underlying data. This method requires
-    /// `&mut self`, ensuring the caller has the only reference to it.
+    /// Returns a mutable reference to the underlying data. This method requires `&mut self`,
+    /// ensuring the caller has the only reference to it.
     ///
     /// # Examples
     ///

src/clone.rs

@@ -1,21 +1,19 @@
 //! Provides the [`PureClone`] trait, which is a restrictive form of `Clone` that does not mutate
-//! the containing [`Cell`].
+//! the containing [`Cell`](crate::cell::Cell).
 //!
-//! Conceptually, the relationship between [`Copy`], [`Clone`], and `PureClone` can be
-//! thought of as follows:
+//! Conceptually, the relationship between [`Copy`], [`Clone`], and `PureClone` can be thought of as
+//! follows:
 //! ```text
 //! Copy: PureClone: Clone
 //! ```
 //!
-//! `PureClone` is `unsafe` because the `clone` implementation must not mutate the
-//! content of `Cell` through the `&self` reference it gets with interior
-//! mutability. See this [Stack Overflow answer] and this [Rust forum thread] for
-//! details.
+//! `PureClone` is `unsafe` because the `clone` implementation must not mutate the content of `Cell`
+//! through the `&self` reference it gets with interior mutability. See this [Stack Overflow answer]
+//! and this [Rust forum thread] for details.
 //!
 //! When this [`crate`] is built with the `"derive"` feature, the [`PureClone`](derive@PureClone)
 //! proc macro can be used to derive `PureClone` for user types.
 //!
-//! [`Cell`]: crate::cell::Cell
 //! [Rust forum thread]:
 //! https://users.rust-lang.org/t/why-does-cell-require-copy-instead-of-clone/5769/3
 //! [Stack Overflow answer]:
@@ -61,9 +59,7 @@ pub use crate::derive::PureClone;
 
 /// The `PureClone` trait, which is a subtrait of [`Clone`].
 ///
-/// See the [module] documentation for more information.
-///
-/// [module]: self
+/// See the [module](self) documentation for more information.
 pub unsafe trait PureClone: Clone {
     /// The `pure_clone` method.
     #[inline]

src/lib.rs

@@ -1,30 +1,22 @@
-//! This crate provides a [`Cell`](cell::Cell) implementation that works with types whose `Clone`
-//! implementations are guaranteed not to mutate the `Cell` content using the `&self`
-//! reference. This is enforced with the provided [`PureClone`] trait, which is a subtrait of
-//! [`Clone`] (and a logical supertrait of [`Copy`]). It is only implemented for types with
-//! compliant `clone` methods.
+//! This crate provides a [`Cell`](cell::Cell) implementation that works with types whose `clone`
+//! methods are guaranteed not to mutate the `Cell` content using the `&self` reference. This is
+//! enforced with the provided [`PureClone`] trait, which is a subtrait of [`Clone`] (and a logical
+//! supertrait of [`Copy`]). It is only implemented for types with a compliant `clone` method.
 //!
 //! See the [`cell`](module@cell) module documentation for more information on how to use it.
 //!
 //! # Background
 //!
-//! This crate was largely inspired by the Swift programming language's class properties (fields in
-//! Rust speak), which have value semantics. In Swift, class types themselves have reference
-//! semantics and are shared. But methods on class types are mutating. My observation is that the
-//! Swift compiler is able to guarantee memory safety in a single-threaded context because copy
-//! constructors are not defined by the user. Intead, the compiler automatically generates ones that
-//! simply perform a field-wise clone.
-//!
-//! In Rust, to enable interiorly mutating methods on a `struct` stored in an [`Rc`](alloc::rc::Rc)
-//! without the overhead of a [`RefCell`](core::cell::RefCell), we can wrap each of the fields in a
-//! [`core::cell::Cell`]. But its [`get`](core::cell::Cell::get) method is only implemented for
-//! types that are `Copy`. This is because if the `clone` method obtains a reference to the `Cell`'s
-//! interior, it may be able to mutate its state. This can cause undefined behavior, as demonstrated
-//! in this [example].
+//! To enable interiorly mutating methods on a type stored in an [`Rc`](alloc::rc::Rc) without the
+//! overhead of a [`RefCell`](core::cell::RefCell), we can wrap each of its fields in a
+//! [`core::cell::Cell`]. But `Cell`'s [`get`](core::cell::Cell::get) method is only implemented for
+//! types that are `Copy`. This is because if the `clone` method obtains a reference to the
+//! containing `Cell`, it may be able to mutate its state. This can cause undefined behavior, as
+//! demonstrated in this [example].
 //!
 //! By restricting ourselves to a checked subset of `Clone` implementations that do not exploit
 //! interior mutability to mutate the `Cell` content, it becomes possible to provide a `Cell` with a
-//! `get` method that does not require `Copy` types.
+//! `get` method that does not require the type to be `Copy`.
 //!
 //! See the documentation for [`PureClone`] for a list of implemented types and the [`clone`] module
 //! documentation for more details.
@@ -43,8 +35,8 @@
 //! ## Interaction with specialization
 //!
 //! The [`PureClone`](derive@clone::PureClone) proc macro generates:
-//! 1. A non-`default` `Clone` impl with trait bounds that ensure any fields with generics are also
-//! `Clone`; and
+//! 1. A non-`default` `Clone` impl with trait bounds that ensure any fields with generic parameters
+//! are also `Clone`; and
 //! 1. A `PureClone` impl that only compiles if all fields are also `PureClone`.
 //!
 //! Item 1 is non-`default` and hence cannot be further specialized.

tests/ui/field_not_clone.stderr

@@ -14,7 +14,7 @@ error[E0277]: the trait bound `Foo: PureClone` is not satisfied
    |        ^^^ the trait `PureClone` is not implemented for `Foo`
    |
 note: required by `pure_clone`
-  --> $DIR/clone.rs:70:5
+  --> $DIR/clone.rs:66:5
    |
-70 |     fn pure_clone(&self) -> Self {
+66 |     fn pure_clone(&self) -> Self {
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

tests/ui/field_not_pure_clone.stderr

@@ -5,7 +5,7 @@ error[E0277]: the trait bound `Foo: PureClone` is not satisfied
    |        ^^^ the trait `PureClone` is not implemented for `Foo`
    |
 note: required by `pure_clone`
-  --> $DIR/clone.rs:70:5
+  --> $DIR/clone.rs:66:5
    |
-70 |     fn pure_clone(&self) -> Self {
+66 |     fn pure_clone(&self) -> Self {
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^