Rewrite comments about dropping and leaking.

Author: kpreid

library/core/src/clone.rs

@@ -336,19 +336,29 @@ pub struct AssertParamIsCopy<T: Copy + ?Sized> {
 /// // The offset of `self.contents` is dynamic because it depends on the alignment of T
 /// // which can be dynamic (if `T = dyn SomeTrait`). Therefore, we have to obtain it
 /// // dynamically by examining `self`, rather than using `offset_of!`.
-/// let offset_of_contents =
-/// (&raw const self.contents).byte_offset_from_unsigned(&raw const *self);
-///
-/// // Since `flag` implements `Copy`, we can just copy it.
-/// // We use `pointer::write()` instead of assignment because the destination must be
-/// // assumed to be uninitialized, whereas an assignment assumes it is initialized.
-/// dest.add(offset_of!(Self, flag)).cast::<bool>().write(self.flag);
-///
-/// // Note: if `flag` owned any resources (i.e. had a `Drop` implementation), then we
-/// // must prepare to drop it in case `self.contents.clone_to_uninit()` panics.
-/// // In this simple case, where we have exactly one field for which `mem::needs_drop()`
-/// // might be true (`contents`), we don’t need to care about cleanup or ordering.
-/// self.contents.clone_to_uninit(dest.add(offset_of_contents));
+/// //
+/// // SAFETY: `self` by definition points somewhere before `&self.contents` in the same
+/// // allocation.
+/// let offset_of_contents = unsafe {
+/// (&raw const self.contents).byte_offset_from_unsigned(self)
+/// };
+///
+/// // Clone each field of `self` into `dest`.
+/// //
+/// // Since `flag` is `Sized`, we could also clone it as
+/// // dest.add(offset_of!(Self, flag)).cast::<bool>().write(self.flag.clone());
+/// // Since it is `Copy` (and therefore does not have a destructor), we could even write
+/// // *dest.add(offset_of!(Self, flag)) = self.flag;
+/// // but that must not be used for types with destructors, since it would read the place
+/// // in order to drop the old value. We have chosen to do neither of those, to demonstrate
+/// // the most general pattern.
+/// //
+/// // SAFETY: The caller must provide a `dest` such that these offsets are valid
+/// // to write to.
+/// unsafe {
+/// self.flag.clone_to_uninit(dest.add(offset_of!(Self, flag)));
+/// self.contents.clone_to_uninit(dest.add(offset_of_contents));
+/// }
 ///
 /// // All fields of the struct have been initialized, therefore the struct is initialized,
 /// // and we have satisfied our `unsafe impl CloneToUninit` obligations.
@@ -370,6 +380,7 @@ pub struct AssertParamIsCopy<T: Copy + ?Sized> {
 ///
 /// assert_eq!(first.contents, [1, 2, 3, 4]);
 /// assert_eq!(second.contents, [10, 20, 30, 40]);
+/// assert_eq!(second.flag, true);
 /// }
 /// ```
 ///
@@ -414,9 +425,8 @@ pub unsafe trait CloneToUninit {
  /// read or dropped, because even if it was previously valid, it may have been partially
  /// overwritten.
  ///
- /// The caller may also need to take care to deallocate the allocation pointed to by `dest`,
- /// if applicable, to avoid a memory leak, and may need to take other precautions to ensure
- /// soundness in the presence of unwinding.
+ /// The caller may wish to to take care to deallocate the allocation pointed to by `dest`,
+ /// if applicable, to avoid a memory leak (but this is not a requirement).
  ///
  /// Implementors should avoid leaking values by, upon unwinding, dropping all component values
  /// that might have already been created. (For example, if a `[Foo]` of length 3 is being