From 554c2735c8dd924fd7cebe863b529d91bb0cac0d Mon Sep 17 00:00:00 2001
From: TD-Sky <three-dim-sky@foxmail.com>
Date: Fri, 4 Aug 2023 12:54:19 +0800
Subject: [PATCH] doc(restore_all): describe how to retry restoring when
 encountering `RestoreCollision` error

---
 src/lib.rs | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 8bab380..8c48268 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -368,15 +368,32 @@ pub mod os_limited {
     ///
     /// # Example
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// use std::fs::File;
     /// use trash::os_limited::{list, restore_all};
+    ///
     /// let filename = "trash-restore_all-example";
     /// File::create(filename).unwrap();
     /// restore_all(list().unwrap().into_iter().filter(|x| x.name == filename)).unwrap();
     /// std::fs::remove_file(filename).unwrap();
     /// ```
     ///
+    /// Retry restoring when encountering [`RestoreCollision`] error:
+    ///
+    /// ```no_run
+    /// use trash::os_limited::{list, restore_all};
+    /// use trash::Error::RestoreCollision;
+    ///
+    /// let items = list().unwrap();
+    /// if let Err(RestoreCollision { path, mut remaining_items }) = restore_all(items) {
+    ///     // keep all except the one(s) that couldn't be restored
+    ///     remaining_items.retain(|e| e.original_path() != path);
+    ///     restore_all(remaining_items).unwrap();
+    /// }
+    /// ```
+    ///
     /// [`RestoreCollision`]: Error::RestoreCollision
     /// [`RestoreTwins`]: Error::RestoreTwins
     pub fn restore_all<I>(items: I) -> Result<(), Error>