Per-entry expiration: Write more docs

src/future/cache.rs

@@ -310,14 +310,20 @@ use std::{
 ///
 /// ## Per-entry expiration policy
 ///
-/// `Cache` supports per-entry expiration policy via the [`Expiry`][expiry-trait]
-/// trait.
+/// `Cache` supports per-entry expiration policy through the `Expiry` trait.
 ///
-/// When a cached entry is inserted, read or updated, a duration can be specified for
-/// that individual entry. The entry will be expired after the specified duration
-/// past from the operation.
+/// `Expiry` trait provides three callback methods:
+/// [`expire_after_create`][exp-create], [`expire_after_read`][exp-read] and
+/// [`expire_after_update`][exp-update]. When a an cache entry is inserted, read or
+/// updated, one of these methods is called. These methods return an
+/// `Option<Duration>`, which is used as the expiration duration of the entry.
 ///
-/// [expiry-trait]: ../trait.Expiry.html
+/// `Expiry` trait provides the default implementations of these methods, so you
+/// will implement only the methods you want to customize.
+///
+/// [exp-create]: ../trait.Expiry.html#method.expire_after_create
+/// [exp-read]: ../trait.Expiry.html#method.expire_after_read
+/// [exp-update]: ../trait.Expiry.html#method.expire_after_update
 ///
 /// ```rust
 /// // Cargo.toml
@@ -442,10 +448,6 @@ use std::{
 /// }
 /// ```
 ///
-/// The `Expiry` trait provides three methods `expire_after_create`,
-/// `expire_after_read` and `expire_after_update` with default implementations. See
-/// [its document][expiry-trait] for more details.
-///
 /// # Example: Eviction Listener
 ///
 /// A `Cache` can be configured with an eviction listener, a closure that is called

src/policy.rs

@@ -80,7 +80,7 @@ pub trait Expiry<K, V> {
     /// Specifies that the entry should be automatically removed from the cache once
     /// the duration has elapsed after the entry's creation. This method is called
     /// for cache write methods such as `insert` and `get_with` but only when the key
-    /// is not present in the cache.
+    /// was not present in the cache.
     ///
     /// # Parameters
     ///

src/sync/cache.rs

@@ -263,14 +263,20 @@ use std::{
 ///
 /// ## Per-entry expiration policy
 ///
-/// `Cache` supports per-entry expiration policy via the [`Expiry`][expiry-trait]
-/// trait.
+/// `Cache` supports per-entry expiration policy through the `Expiry` trait.
 ///
-/// When a cached entry is inserted, read or updated, a duration can be specified for
-/// that individual entry. The entry will be expired after the specified duration
-/// past from the operation.
+/// `Expiry` trait provides three callback methods:
+/// [`expire_after_create`][exp-create], [`expire_after_read`][exp-read] and
+/// [`expire_after_update`][exp-update]. When a an cache entry is inserted, read or
+/// updated, one of these methods is called. These methods return an
+/// `Option<Duration>`, which is used as the expiration duration of the entry.
 ///
-/// [expiry-trait]: ../trait.Expiry.html
+/// `Expiry` trait provides the default implementations of these methods, so you
+/// will implement only the methods you want to customize.
+///
+/// [exp-create]: ../trait.Expiry.html#method.expire_after_create
+/// [exp-read]: ../trait.Expiry.html#method.expire_after_read
+/// [exp-update]: ../trait.Expiry.html#method.expire_after_update
 ///
 /// ```rust
 /// use moka::{sync::Cache, Expiry};
@@ -378,10 +384,6 @@ use std::{
 /// println!("\nDone!");
 /// ```
 ///
-/// The `Expiry` trait provides three methods `expire_after_create`,
-/// `expire_after_read` and `expire_after_update` with default implementations. See
-/// [its document][expiry-trait] for more details.
-///
 /// # Example: Eviction Listener
 ///
 /// A `Cache` can be configured with an eviction listener, a closure that is called