chore: document behaviors and requirements.

Author: Kokoro2336

plugins/recent-doc/guest-js/index.ts

@@ -4,14 +4,76 @@
 
 import { invoke } from '@tauri-apps/api/core'
 
+/**
+ * Manage the operating system recent documents list.
+ *
+ * @module
+ */
+
+/**
+ * Adds a document to this app's recent documents list.
+ *
+ * #### Platform-specific
+ *
+ * - **Linux / Android / iOS:** Unsupported.
+ *
+ * @param path Local filesystem path to the document.
+ *
+ * @example
+ * ```typescript
+ * import { addRecentDocument } from '@tauri-apps/plugin-recent-doc';
+ * await addRecentDocument('/path/to/document.txt');
+ * ```
+ *
+ * This function rejects when called on an unsupported platform.
+ * On Windows, it also rejects if the native shell API fails (for example, when the path cannot be resolved).
+ *
+ * @since 2.0.0
+ */
 async function addRecentDocument(path: string): Promise<void> {
   return invoke('plugin:recent-doc|add_recent_document', { path })
 }
 
+/**
+ * Gets this app's recent documents list from the operating system.
+ *
+ * #### Platform-specific
+ *
+ * - **Linux / Android / iOS:** Unsupported.
+ *
+ * @example
+ * ```typescript
+ * import { getRecentDocuments } from '@tauri-apps/plugin-recent-doc';
+ * const recent = await getRecentDocuments();
+ * ```
+ *
+ * This function rejects when called on an unsupported platform.
+ * On Windows, it also rejects if the native shell API fails.
+ *
+ * @since 2.0.0
+ */
 async function getRecentDocuments(): Promise<string[]> {
   return invoke<string[]>('plugin:recent-doc|get_recent_documents')
 }
 
+/**
+ * Clears this app's recent documents list in the operating system.
+ *
+ * #### Platform-specific
+ *
+ * - **Linux / Android / iOS:** Unsupported.
+ *
+ * @example
+ * ```typescript
+ * import { clearRecentDocuments } from '@tauri-apps/plugin-recent-doc';
+ * await clearRecentDocuments();
+ * ```
+ *
+ * This function rejects when called on an unsupported platform.
+ * On Windows, it also rejects if the native shell API fails.
+ *
+ * @since 2.0.0
+ */
 async function clearRecentDocuments(): Promise<void> {
   return invoke('plugin:recent-doc|clear_recent_documents')
 }

plugins/recent-doc/src/commands.rs

@@ -52,6 +52,19 @@ impl Drop for ComGuard {
     }
 }
 
+/// Adds a document to this app's recent documents list on the host OS.
+/// You can see the added document in the Jump List on Windows or the Recent Items menu on macOS.
+///
+/// # Requirements
+///
+/// - This API is supported on Windows and macOS only.
+/// - `path` should be a local filesystem path that the operating system can resolve.
+///
+/// # Errors
+///
+/// Returns:
+/// - `Error::UnsupportedPlatform` when called on an unsupported platform.
+/// - `Error::WindowsError` on Windows when native shell APIs fail.
 #[command]
 pub fn add_recent_document<R: Runtime>(_app: AppHandle<R>, _path: &str) -> Result<()> {
     #[cfg(target_os = "windows")]
@@ -91,6 +104,18 @@ pub fn add_recent_document<R: Runtime>(_app: AppHandle<R>, _path: &str) -> Resul
     Ok(())
 }
 
+/// Clears this app's recent documents list on the host OS.
+/// After clearing, the Jump List on Windows or the Recent Items menu on macOS will be empty until new documents are added with `add_recent_document`.
+///
+/// # Requirements
+///
+/// - This API is supported on Windows and macOS only.
+///
+/// # Errors
+///
+/// Returns:
+/// - `Error::UnsupportedPlatform` when called on an unsupported platform.
+/// - `Error::WindowsError` on Windows when native shell APIs fail.
 #[command]
 pub fn clear_recent_documents<R: Runtime>(_app: AppHandle<R>) -> Result<()> {
     #[cfg(target_os = "windows")]
@@ -121,6 +146,17 @@ pub fn clear_recent_documents<R: Runtime>(_app: AppHandle<R>) -> Result<()> {
     Ok(())
 }
 
+/// Gets this app's recent documents list from the host OS.
+///
+/// # Requirements
+///
+/// - This API is supported on Windows and macOS only.
+///
+/// # Errors
+///
+/// Returns:
+/// - `Error::UnsupportedPlatform` when called on an unsupported platform.
+/// - `Error::WindowsError` on Windows when native shell APIs fail.
 #[command]
 pub fn get_recent_documents<R: Runtime>(_app: AppHandle<R>) -> Result<Vec<String>> {
     #[allow(unused_mut)]