chore: update documentation

plugins/shell/src/error.rs

@@ -6,17 +6,27 @@ use std::path::PathBuf;
 
 use serde::{Serialize, Serializer};
 
+/// Errors returned by the shell plugin.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Failed to invoke the mobile plugin implementation.
+    ///
+    /// Only available on mobile.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(#[from] tauri::plugin::mobile::PluginInvokeError),
+    /// I/O error, usually raised when spawning a process or reading its output.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// The path of the current executable has no parent directory,
+    /// so the path of a sidecar program could not be resolved.
     #[error("current executable path has no parent")]
     CurrentExeHasNoParent,
+    /// The string does not match any of the known programs
+    /// accepted by the deprecated `open` API.
     #[error("unknown program {0}")]
     UnknownProgramName(String),
+    /// The command is not allowed by the configured shell scope.
     #[error(transparent)]
     Scope(#[from] crate::scope::Error),
     /// Sidecar not allowed by the configuration.
@@ -25,6 +35,7 @@ pub enum Error {
     /// Program not allowed by the scope.
     #[error("program not allowed on the configured shell scope: {0}")]
     ProgramNotAllowed(PathBuf),
+    /// The `encoding` spawn option is neither `raw` nor a label of a known character encoding.
     #[error("unknown encoding {0}")]
     UnknownEncoding(String),
     /// JSON error.

plugins/shell/src/lib.rs

@@ -29,6 +29,7 @@ mod error;
 #[deprecated(since = "2.1.0", note = "Use tauri-plugin-opener instead.")]
 #[allow(deprecated)]
 pub mod open;
+/// Types and helpers to spawn and interact with child processes.
 pub mod process;
 mod scope;
 mod scope_entry;
@@ -45,6 +46,9 @@ tauri::ios_plugin_binding!(init_plugin_shell);
 
 type ChildStore = Arc<Mutex<HashMap<u32, CommandChild>>>;
 
+/// Access to the shell APIs.
+///
+/// Get an instance of this type with [`ShellExt::shell`].
 pub struct Shell<R: Runtime> {
     #[allow(dead_code)]
     app: AppHandle<R>,
@@ -90,7 +94,21 @@ impl<R: Runtime> Shell<R> {
     }
 }
 
+/// Extensions to [`tauri::App`], [`tauri::AppHandle`], [`tauri::WebviewWindow`],
+/// [`tauri::Webview`] and [`tauri::Window`] to access the shell APIs.
 pub trait ShellExt<R: Runtime> {
+    /// Gets the shell APIs.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tauri_plugin_shell::ShellExt;
+    ///
+    /// async fn run_echo<R: tauri::Runtime>(app: &tauri::AppHandle<R>) {
+    ///     let output = app.shell().command("echo").args(["hello"]).output().await.unwrap();
+    ///     println!("{}", String::from_utf8_lossy(&output.stdout));
+    /// }
+    /// ```
     fn shell(&self) -> &Shell<R>;
 }
 
@@ -100,6 +118,18 @@ impl<R: Runtime, T: Manager<R>> ShellExt<R> for T {
     }
 }
 
+/// Initializes the shell plugin.
+///
+/// The plugin state can be accessed with [`ShellExt::shell`],
+/// and all spawned child processes are killed when the application exits.
+///
+/// # Examples
+///
+/// ```no_run
+/// fn setup<R: tauri::Runtime>(builder: tauri::Builder<R>) -> tauri::Builder<R> {
+///     builder.plugin(tauri_plugin_shell::init())
+/// }
+/// ```
 pub fn init<R: Runtime>() -> TauriPlugin<R, Option<config::Config>> {
     Builder::<R, Option<config::Config>>::new("shell")
         .js_init_script(include_str!("init-iife.js").to_string())