chore: update documentation

plugins/http/guest-js/index.ts

@@ -48,6 +48,11 @@ export interface Proxy {
   https?: string | ProxyConfig
 }
 
+/**
+ * Detailed configuration of a single proxy server, used when a plain URL string is not enough.
+ *
+ * @since 2.0.0
+ */
 export interface ProxyConfig {
   /**
    * The URL of the proxy server.
@@ -57,7 +62,13 @@ export interface ProxyConfig {
    * Set the `Proxy-Authorization` header using Basic auth.
    */
   basicAuth?: {
+    /**
+     * The user name sent to the proxy server.
+     */
     username: string
+    /**
+     * The password sent to the proxy server.
+     */
     password: string
   }
   /**
@@ -116,14 +127,24 @@ const ERROR_REQUEST_CANCELLED = 'Request cancelled'
  * Fetch a resource from the network. It returns a `Promise` that resolves to the
  * `Response` to that `Request`, whether it is successful or not.
  *
+ * The request is performed by the Rust backend instead of the webview, so it is not subject to
+ * CORS, but the URL must be allowed by the plugin scope.
+ *
  * @example
  * ```typescript
+ * import { fetch } from '@tauri-apps/plugin-http';
  * const response = await fetch("http://my.json.host/data.json");
  * console.log(response.status);  // e.g. 200
  * console.log(response.statusText); // e.g. "OK"
  * const jsonData = await response.json();
  * ```
  *
+ * @param input The resource to fetch, as a URL, a string or a `Request` object.
+ * @param init The standard `fetch` request options, extended with the Rust client options from
+ * {@linkcode ClientOptions}: `maxRedirections`, `connectTimeout`, `proxy` and `danger`. The
+ * `signal` option can be used to abort the request.
+ * @returns A promise resolving to the `Response` of the request.
+ *
  * @since 2.0.0
  */
 export async function fetch(

plugins/http/src/error.rs

@@ -5,42 +5,68 @@
 use serde::{Serialize, Serializer};
 use url::Url;
 
+/// Errors that can happen while using the HTTP plugin.
+///
+/// The error is serialized to the frontend as its [`Display`](std::fmt::Display) string.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// JSON serialization or deserialization error.
     #[error(transparent)]
     Json(#[from] serde_json::Error),
+    /// File system error, raised for instance when the cookie store file cannot be created or
+    /// opened on startup.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// Error from the underlying [`reqwest`] client, raised while building the client, sending the
+    /// request or reading the response body.
     #[error(transparent)]
     Network(#[from] reqwest::Error),
+    /// Error from the [`http`] crate, raised while building the response of a `data:` URL.
     #[error(transparent)]
     Http(#[from] http::Error),
+    /// A header name given by the frontend is not a valid HTTP header name.
     #[error(transparent)]
     HttpInvalidHeaderName(#[from] http::header::InvalidHeaderName),
+    /// A header value is not a valid HTTP header value.
     #[error(transparent)]
     HttpInvalidHeaderValue(#[from] http::header::InvalidHeaderValue),
     /// URL not allowed by the scope.
+    ///
+    /// Raised for the URL requested by the frontend, and - when the
+    /// [`scope_redirects`](crate::Config::scope_redirects) configuration is enabled - for any
+    /// redirect target that is not allowed by the scope.
     #[error("url not allowed on the configured scope: {0}")]
     UrlNotAllowed(Url),
+    /// Failed to parse a URL.
     #[error(transparent)]
     UrlParseError(#[from] url::ParseError),
     /// HTTP method error.
     #[error(transparent)]
     HttpMethod(#[from] http::method::InvalidMethod),
+    /// The requested URL uses an unsupported scheme. Only `http`, `https` and `data` are handled.
     #[error("scheme {0} not supported")]
     SchemeNotSupport(String),
+    /// The request was aborted by the frontend before the response was received.
     #[error("Request canceled")]
     RequestCanceled,
+    /// Error from the file system plugin.
     #[error(transparent)]
     FsError(#[from] tauri_plugin_fs::Error),
+    /// The `data:` URL could not be processed.
     #[error("failed to process data url")]
     DataUrlError,
+    /// The body of the `data:` URL could not be decoded into bytes.
     #[error("failed to decode data url into bytes")]
     DataUrlDecodeError,
+    /// Error from the Tauri APIs, raised for instance while resolving a path or while reading the
+    /// webview resource table.
     #[error(transparent)]
     Tauri(#[from] tauri::Error),
+    /// A response header value is not valid UTF-8, so it cannot be forwarded to the frontend.
     #[error(transparent)]
     Utf8(#[from] std::string::FromUtf8Error),
+    /// The frontend requested dangerous client settings, but the `dangerous-settings` Cargo
+    /// feature is not enabled.
     #[error("dangerous settings used but are not enabled")]
     DangerousSettings,
 }
@@ -54,4 +80,5 @@ impl Serialize for Error {
     }
 }
 
+/// Alias for a [`Result`](std::result::Result) with the error type [`Error`].
 pub type Result<T> = std::result::Result<T, Error>;

plugins/http/src/lib.rs

@@ -84,6 +84,16 @@ pub(crate) struct Http {
     cookies_jar: std::sync::Arc<crate::reqwest_cookie_store::CookieStoreMutex>,
 }
 
+/// Initializes the plugin.
+///
+/// The plugin reads its [`Config`] from the `plugins > http` object of the `tauri.conf.json` file;
+/// when that object is missing, [`Config::default`] is used.
+///
+/// With the `cookies` Cargo feature (enabled by default), a cookie jar is loaded from a `.cookies`
+/// file in the application cache directory on setup and written back to it when the application
+/// exits. A jar that cannot be read is replaced by an empty one.
+///
+/// Register it on the Tauri builder with `.plugin(tauri_plugin_http::init())`.
 pub fn init<R: Runtime>() -> TauriPlugin<R, Option<Config>> {
     Builder::<R, Option<Config>>::new("http")
         .setup(|app, api| {