chore: update documentation

plugins/upload/guest-js/index.ts

@@ -2,23 +2,89 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Upload files from disk to a remote server over HTTP, and download files from a remote HTTP
+ * server to disk.
+ *
+ * @module
+ */
+
 import { invoke, Channel } from '@tauri-apps/api/core'
 
+/**
+ * The payload sent to a {@link ProgressHandler} while an upload or download is in progress.
+ */
 interface ProgressPayload {
+  /**
+   * The number of bytes transferred since the previous progress event (i.e. the size of the
+   * last chunk), not the cumulative total.
+   */
   progress: number
+  /**
+   * The cumulative number of bytes transferred so far.
+   */
   progressTotal: number
+  /**
+   * The total size of the transfer in bytes. For a download this is the value of the response's
+   * `Content-Length` header, and is `0` if the server did not send it or the response body is
+   * compressed. For an upload this is the size of the file being uploaded.
+   */
   total: number
+  /**
+   * The current transfer speed, approximately in bytes per second. It is recalculated about
+   * every 500 milliseconds and stays at `0` until then.
+   */
   transferSpeed: number
 }
 
+/**
+ * A callback invoked with a {@link ProgressPayload} every time a chunk of data is
+ * uploaded or downloaded.
+ */
 type ProgressHandler = (progress: ProgressPayload) => void
 
+/**
+ * The HTTP method used to send the file to the server in {@link upload}.
+ */
 enum HttpMethod {
+  /**
+   * Send the file using an HTTP `POST` request. This is the default when no method is given.
+   */
   Post = 'POST',
+  /**
+   * Send the file using an HTTP `PUT` request.
+   */
   Put = 'PUT',
+  /**
+   * Send the file using an HTTP `PATCH` request.
+   */
   Patch = 'PATCH'
 }
 
+/**
+ * Uploads a file at the given path to a URL, using the file's contents as the request body.
+ *
+ * @example
+ * ```typescript
+ * import { upload } from '@tauri-apps/plugin-upload';
+ *
+ * await upload(
+ *   'https://example.com/file-upload',
+ *   './path/to/my/file.txt',
+ *   ({ progress, total }) => console.log(`Uploaded ${progress} of ${total} bytes`),
+ *   { 'Content-Type': 'text/plain' }
+ * );
+ * ```
+ *
+ * @param url The URL to upload the file to.
+ * @param filePath The path of the file to upload.
+ * @param progressHandler A callback invoked with upload progress updates.
+ * @param headers Additional request headers to send with the upload.
+ * @param method The HTTP method used to send the file. Defaults to {@link HttpMethod.Post}.
+ * @returns A promise resolving to the response body as text.
+ *
+ * @since 2.0.0
+ */
 async function upload(
   url: string,
   filePath: string,
@@ -46,10 +112,32 @@ async function upload(
   })
 }
 
-/// Download file from given url.
-///
-/// Note that `filePath` currently must include the file name.
-/// Furthermore the progress events will report a total length of 0 if the server did not sent a `Content-Length` header or if the file is compressed.
+/**
+ * Downloads a file from a given URL and writes it to the given path on disk.
+ *
+ * @example
+ * ```typescript
+ * import { download } from '@tauri-apps/plugin-upload';
+ *
+ * await download(
+ *   'https://example.com/file-download-link',
+ *   './path/to/save/my/file.txt',
+ *   ({ progress, total }) => console.log(`Downloaded ${progress} of ${total} bytes`),
+ *   { 'Content-Type': 'text/plain' }
+ * );
+ * ```
+ *
+ * @param url The URL to download the file from.
+ * @param filePath The path to save the file to. It must include the file name.
+ * @param progressHandler A callback invoked with download progress updates. The reported
+ * `total` will be `0` if the server did not send a `Content-Length` header or the response body
+ * is compressed.
+ * @param headers Additional request headers to send with the download request.
+ * @param body An optional request body. When provided, the download is requested with an HTTP
+ * `POST` request using this value as the body; otherwise an HTTP `GET` request is used.
+ *
+ * @since 2.0.0
+ */
 async function download(
   url: string,
   filePath: string,

plugins/upload/src/lib.rs

@@ -38,24 +38,39 @@ use read_progress_stream::ReadProgressStream;
 
 use std::collections::HashMap;
 
+/// The HTTP method used to send the file in the `upload` command.
+///
+/// Serialized as an uppercase string (`"POST"`, `"PUT"` or `"PATCH"`) to match the JavaScript
+/// guest bindings.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "UPPERCASE")]
 pub enum HttpMethod {
+    /// Send the file with an HTTP `POST` request. This is the default when no method is given.
     Post,
+    /// Send the file with an HTTP `PUT` request.
     Put,
+    /// Send the file with an HTTP `PATCH` request.
     Patch,
 }
 
 type Result<T> = std::result::Result<T, Error>;
 
+/// The error type returned by this plugin's `upload` and `download` commands.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// An I/O error, for example failing to open, read or write the file at the given path, or
+    /// the background task that performs the transfer panicking.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+    /// An error returned by the underlying [`reqwest`] HTTP client while sending the request or
+    /// reading the response.
     #[error(transparent)]
     Request(#[from] reqwest::Error),
+    /// The content length of the request or response could not be determined.
     #[error("{0}")]
     ContentLength(String),
+    /// The HTTP response did not indicate success. Contains the status code and the response
+    /// body text.
     #[error("request failed with status code {0}: {1}")]
     HttpErrorCode(u16, String),
 }
@@ -193,6 +208,7 @@ fn file_to_body(channel: Channel<ProgressPayload>, file: File, file_len: u64) ->
     ))
 }
 
+/// Initializes the upload plugin, registering the `upload` and `download` commands.
 pub fn init<R: Runtime>() -> TauriPlugin<R> {
     PluginBuilder::new("upload")
         .invoke_handler(tauri::generate_handler![download, upload])