Core Lib Documentation: Clone module

corelib/src/clone.cairo

@@ -1,4 +1,51 @@
+//! The `Clone` trait provides the ability to duplicate instances of types that cannot be
+//! 'implicitly copied'.
+//!
+//! In Cairo, some simple types are "implicitly copyable": when you assign them or pass them as
+//! arguments, the receiver will get a copy, leaving the original value in place. These types do not
+//! require allocation to copy, and are not at risk of accessing un-allocated memory, so the
+//! compiler considers them cheap and safe to copy. For other types, copies must be made explicitly,
+//! by convention implementing the [`Clone`] trait and calling the [`Clone::clone`] method.
+//!
+//! # Examples
+//!
+//! ```
+//! let arr = array![1, 2, 3];
+//! let cloned_arr = arr.clone();
+//! assert!(arr == cloned_arr);
+//! ```
+//!
+//! To easily implement the `Clone` trait, you can also use
+//! `#[derive(Clone)]`:
+//!
+//! ```
+//! #[derive(Clone, Drop)]
+//! struct Sheep {
+//!    name: ByteArray,
+//!    age: u8,
+//! }
+//!
+//! fn main() {
+//!    let dolly = Sheep {
+//!        name: "Dolly",
+//!        age: 6,
+//!    };
+//!
+//!    let cloned_sheep = dolly.clone();  // Famous cloned sheep!
+//!}
+//! ```
+
+/// `Clone` trait defines the interface for cloning values.
 pub trait Clone<T> {
+    /// Takes a snapshot of a copyable value and returns a clone of that value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let arr = array![1, 2, 3];
+    /// let cloned_arr = arr.clone();
+    /// assert!(arr == cloned_arr);
+    /// ```
     #[must_use]
     fn clone(self: @T) -> T;
 }
@@ -9,7 +56,6 @@ impl TCopyClone<T, +Copy<T>> of Clone<T> {
     }
 }
 
-/// Tuple `Clone` implementation.
 impl TupleClone<
     T,
     impl TSF: crate::metaprogramming::TupleSnapForward<T>,
@@ -21,36 +67,32 @@ impl TupleClone<
     }
 }
 
-/// Trait helper for implementing `Clone` for tuples.
-/// Provides a `Clone` function for tuples of snapshots, and basic snapshots.
+// Trait helper for implementing `Clone` for tuples.
+// Provides a `clone` function for tuples of snapshots, and basic snapshots.
 trait CloneHelper<T, Cloned> {
     fn clone(value: T) -> Cloned;
 }
 
-/// An implementation of `CloneHelper` for a snapshot of any type with `Clone`
-/// implementation.
 impl CloneHelperByClone<T, +Clone<T>> of CloneHelper<@T, T> {
     fn clone(value: @T) -> T {
         value.clone()
     }
 }
 
-/// Base implementation of `CloneHelper` for tuples.
 impl CloneHelperBaseTuple of CloneHelper<(), ()> {
     fn clone(value: ()) -> () {
         value
     }
 }
 
-/// Base implementation of `CloneHelper` for fixed-sized arrays.
 impl FixedSizedArrayCloneHelper<T> of CloneHelper<[@T; 0], [T; 0]> {
     fn clone(value: [@T; 0]) -> [T; 0] {
         let [] = value;
         []
     }
 }
 
-/// Recursive implementation of `CloneHelper` for tuple style structs.
+// Recursive implementation of `CloneHelper` for tuple style structs.
 impl TupleNextCloneHelper<
     T,
     impl TH: crate::metaprogramming::TupleSplit<T>,