From 5cd77787239d8a76c2acfdf6db2f9e1f912d73e2 Mon Sep 17 00:00:00 2001
From: Fabian-Lars <github@fabianlars.de>
Date: Sun, 9 Nov 2025 17:07:35 +0100
Subject: [PATCH] docs(dialog): add/fix doc item links, closes #3089 (#3091)

---
 plugins/dialog/src/lib.rs | 39 +++++++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/plugins/dialog/src/lib.rs b/plugins/dialog/src/lib.rs
index 17d9a829d..60be78cd7 100644
--- a/plugins/dialog/src/lib.rs
+++ b/plugins/dialog/src/lib.rs
@@ -467,10 +467,11 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select a single file.
+    ///
     /// This is not a blocking operation,
     /// and should be used when running on the main thread to avoid deadlocks with the event loop.
     ///
-    /// For usage in other contexts such as commands, prefer [`Self::pick_file`].
+    /// See [`Self::blocking_pick_file`] for a blocking version for use in other contexts.
     ///
     /// # Examples
     ///
@@ -490,9 +491,12 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select multiple files.
+    ///
     /// This is not a blocking operation,
     /// and should be used when running on the main thread to avoid deadlocks with the event loop.
     ///
+    /// See [`Self::blocking_pick_files`] for a blocking version for use in other contexts.
+    ///
     /// # Reading the files
     ///
     /// The file paths cannot be read directly on Android as they are behind a content URI.
@@ -535,9 +539,12 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select a single folder.
+    ///
     /// This is not a blocking operation,
     /// and should be used when running on the main thread to avoid deadlocks with the event loop.
     ///
+    /// See [`Self::blocking_pick_folder`] for a blocking version for use in other contexts.
+    ///
     /// # Examples
     ///
     /// ```
@@ -557,9 +564,12 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select multiple folders.
+    ///
     /// This is not a blocking operation,
     /// and should be used when running on the main thread to avoid deadlocks with the event loop.
     ///
+    /// See [`Self::blocking_pick_folders`] for a blocking version for use in other contexts.
+    ///
     /// # Examples
     ///
     /// ```
@@ -583,6 +593,8 @@ impl<R: Runtime> FileDialogBuilder<R> {
     /// This is not a blocking operation,
     /// and should be used when running on the main thread to avoid deadlocks with the event loop.
     ///
+    /// See [`Self::blocking_save_file`] for a blocking version for use in other contexts.
+    ///
     /// # Examples
     ///
     /// ```
@@ -604,8 +616,11 @@ impl<R: Runtime> FileDialogBuilder<R> {
 /// Blocking APIs.
 impl<R: Runtime> FileDialogBuilder<R> {
     /// Shows the dialog to select a single file.
+    ///
     /// This is a blocking operation,
-    /// and should *NOT* be used when running on the main thread context.
+    /// and should *NOT* be used when running on the main thread.
+    ///
+    /// See [`Self::pick_file`] for a non-blocking version for use in main-thread contexts.
     ///
     /// # Examples
     ///
@@ -623,8 +638,11 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select multiple files.
+    ///
     /// This is a blocking operation,
-    /// and should *NOT* be used when running on the main thread context.
+    /// and should *NOT* be used when running on the main thread.
+    ///
+    /// See [`Self::pick_files`] for a non-blocking version for use in main-thread contexts.
     ///
     /// # Examples
     ///
@@ -642,8 +660,11 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select a single folder.
+    ///
     /// This is a blocking operation,
-    /// and should *NOT* be used when running on the main thread context.
+    /// and should *NOT* be used when running on the main thread.
+    ///
+    /// See [`Self::pick_folder`] for a non-blocking version for use in main-thread contexts.
     ///
     /// # Examples
     ///
@@ -662,8 +683,11 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to select multiple folders.
+    ///
     /// This is a blocking operation,
-    /// and should *NOT* be used when running on the main thread context.
+    /// and should *NOT* be used when running on the main thread.
+    ///
+    /// See [`Self::pick_folders`] for a non-blocking version for use in main-thread contexts.
     ///
     /// # Examples
     ///
@@ -682,8 +706,11 @@ impl<R: Runtime> FileDialogBuilder<R> {
     }
 
     /// Shows the dialog to save a file.
+    ///
     /// This is a blocking operation,
-    /// and should *NOT* be used when running on the main thread context.
+    /// and should *NOT* be used when running on the main thread.
+    ///
+    /// See [`Self::save_file`] for a non-blocking version for use in main-thread contexts.
     ///
     /// # Examples
     ///