chore: update documentation

plugins/clipboard-manager/guest-js/index.ts

@@ -20,6 +20,9 @@ import { Image, transformImage } from '@tauri-apps/api/image'
  * assert(await readText(), 'Tauri is awesome!');
  * ```
  *
+ * @param text The plain text to write to the clipboard.
+ * @param opts Additional configuration for the write operation.
+ * @param opts.label A label describing the copied content. **Android only**, ignored on other platforms.
  * @returns A promise indicating the success or failure of the operation.
  *
  * @since 2.0.0
@@ -41,6 +44,7 @@ async function writeText(
  * import { readText } from '@tauri-apps/plugin-clipboard-manager';
  * const clipboardText = await readText();
  * ```
+ * @returns A promise resolving to the clipboard contents as plain text.
  * @since 2.0.0
  */
 async function readText(): Promise<string> {
@@ -67,6 +71,7 @@ async function readText(): Promise<string> {
  * await writeImage(buffer);
  * ```
  *
+ * @param image The image to write, as a path, raw RGBA bytes, or an existing {@link Image}.
  * @returns A promise indicating the success or failure of the operation.
  *
  * @since 2.0.0
@@ -94,6 +99,7 @@ async function writeImage(
  * const blob = new Blob([await clipboardImage.rgba()], { type: 'image' })
  * const url = URL.createObjectURL(blob)
  * ```
+ * @returns A promise resolving to the clipboard contents as an {@link Image}.
  * @since 2.0.0
  */
 async function readImage(): Promise<Image> {
@@ -119,6 +125,8 @@ async function readImage(): Promise<Image> {
  * assert(await readText(), '<h1>Tauri is awesome!</h1>');
  * ```
  *
+ * @param html The HTML markup to write to the clipboard.
+ * @param altText The plain text fallback written alongside the HTML, used by targets that cannot render it.
  * @returns A promise indicating the success or failure of the operation.
  *
  * @since 2.0.0

plugins/clipboard-manager/src/desktop.rs

@@ -28,6 +28,12 @@ pub struct Clipboard<R: Runtime> {
 }
 
 impl<R: Runtime> Clipboard<R> {
+    /// Writes plain text to the system clipboard.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::Clipboard`] if the clipboard could not be initialized or the
+    /// underlying [`arboard`] operation fails.
     pub fn write_text<'a, T: Into<Cow<'a, str>>>(&self, text: T) -> crate::Result<()> {
         match &self.clipboard {
             Ok(clipboard) => clipboard
@@ -41,6 +47,12 @@ impl<R: Runtime> Clipboard<R> {
         }
     }
 
+    /// Writes an image to the system clipboard as RGBA data.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::Clipboard`] if the clipboard could not be initialized or the
+    /// underlying [`arboard`] operation fails.
     pub fn write_image(&self, image: &Image<'_>) -> crate::Result<()> {
         match &self.clipboard {
             Ok(clipboard) => clipboard
@@ -69,6 +81,13 @@ impl<R: Runtime> Clipboard<R> {
         }
     }
 
+    /// Writes HTML to the system clipboard, with an optional plain text fallback for targets
+    /// that cannot render it.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::Clipboard`] if the clipboard could not be initialized or the
+    /// underlying [`arboard`] operation fails.
     pub fn write_html<'a, T: Into<Cow<'a, str>>>(
         &self,
         html: T,
@@ -86,6 +105,12 @@ impl<R: Runtime> Clipboard<R> {
         }
     }
 
+    /// Clears the system clipboard.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::Clipboard`] if the clipboard could not be initialized or the
+    /// underlying [`arboard`] operation fails.
     pub fn clear(&self) -> crate::Result<()> {
         match &self.clipboard {
             Ok(clipboard) => clipboard

plugins/clipboard-manager/src/error.rs

@@ -4,15 +4,20 @@
 
 use serde::{ser::Serializer, Serialize};
 
+/// Alias for `Result<T, Error>` used throughout this crate.
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// Errors that can occur while interacting with the system clipboard.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Forwarding a request to, or receiving a response from, the mobile plugin failed.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),
+    /// The underlying clipboard operation failed, or the operation is not supported on this platform.
     #[error("{0}")]
     Clipboard(String),
+    /// An error forwarded from the Tauri core.
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
 }

plugins/clipboard-manager/src/lib.rs

@@ -31,6 +31,7 @@ pub use mobile::Clipboard;
 
 /// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`], [`tauri::Webview`] and [`tauri::Window`] to access the clipboard APIs.
 pub trait ClipboardExt<R: Runtime> {
+    /// Returns a handle to the [`Clipboard`] APIs.
     fn clipboard(&self) -> &Clipboard<R>;
 }
 

plugins/clipboard-manager/src/mobile.rs

@@ -34,6 +34,11 @@ pub fn init<R: Runtime, C: DeserializeOwned>(
 pub struct Clipboard<R: Runtime>(PluginHandle<R>);
 
 impl<R: Runtime> Clipboard<R> {
+    /// Writes plain text to the system clipboard, without a label.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::PluginInvoke`] if the underlying mobile plugin call fails.
     pub fn write_text<'a, T: Into<Cow<'a, str>>>(&self, text: T) -> crate::Result<()> {
         let text = text.into().to_string();
         self.0
@@ -41,6 +46,13 @@ impl<R: Runtime> Clipboard<R> {
             .map_err(Into::into)
     }
 
+    /// Writes plain text to the system clipboard along with a label describing the content.
+    ///
+    /// The label is only used on Android (it becomes the `ClipData` label); iOS ignores it.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::PluginInvoke`] if the underlying mobile plugin call fails.
     pub fn write_text_with_label<'a, T: Into<Cow<'a, str>>>(
         &self,
         text: T,
@@ -59,12 +71,22 @@ impl<R: Runtime> Clipboard<R> {
             .map_err(Into::into)
     }
 
+    /// Not supported on mobile.
+    ///
+    /// # Errors
+    ///
+    /// Always returns [`crate::Error::Clipboard`].
     pub fn write_image(&self, _image: &Image<'_>) -> crate::Result<()> {
         Err(crate::Error::Clipboard(
             "Unsupported on this platform".to_string(),
         ))
     }
 
+    /// Reads the system clipboard as plain text.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::PluginInvoke`] if the underlying mobile plugin call fails.
     pub fn read_text(&self) -> crate::Result<String> {
         self.0
             .run_mobile_plugin("readText", ())
@@ -74,6 +96,11 @@ impl<R: Runtime> Clipboard<R> {
             .map_err(Into::into)
     }
 
+    /// Not supported on mobile.
+    ///
+    /// # Errors
+    ///
+    /// Always returns [`crate::Error::Clipboard`].
     pub fn read_image(&self) -> crate::Result<Image<'_>> {
         Err(crate::Error::Clipboard(
             "Unsupported on this platform".to_string(),
@@ -81,6 +108,11 @@ impl<R: Runtime> Clipboard<R> {
     }
 
     // Treat HTML as unsupported on mobile until tested
+    /// Not supported on mobile.
+    ///
+    /// # Errors
+    ///
+    /// Always returns [`crate::Error::Clipboard`].
     pub fn write_html<'a, T: Into<Cow<'a, str>>>(
         &self,
         _html: T,
@@ -91,6 +123,14 @@ impl<R: Runtime> Clipboard<R> {
         ))
     }
 
+    /// Clears the system clipboard.
+    ///
+    /// On Android this only works on SDK 28 and above; on older versions the clipboard is
+    /// instead overwritten with an empty string.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::Error::PluginInvoke`] if the underlying mobile plugin call fails.
     pub fn clear(&self) -> crate::Result<()> {
         self.0.run_mobile_plugin("clear", ()).map_err(Into::into)
     }