chore: update documentation

plugins/geolocation/guest-js/index.ts

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Get and track the device's current position, mirroring the W3C Geolocation API.
+ *
+ * @module
+ */
+
 import {
   Channel,
   invoke,
@@ -9,6 +15,9 @@ import {
   checkPermissions as checkPluginPermissions
 } from '@tauri-apps/api/core'
 
+/**
+ * The GPS coordinates of a {@link Position}, along with the accuracy of each reading.
+ */
 export type Coordinates = {
   /**
    * Latitude in decimal degrees.
@@ -31,6 +40,9 @@ export type Coordinates = {
    * The altitude the user is at, if available.
    */
   altitude: number | null
+  /**
+   * The speed the user is traveling, in meters per second, if available.
+   */
   speed: number | null
   /**
    * The heading the user is facing, if available.
@@ -38,6 +50,9 @@ export type Coordinates = {
   heading: number | null
 }
 
+/**
+ * The current permission state for the geolocation APIs.
+ */
 export type PermissionStatus = {
   /**
    * Permission state for the location alias.
@@ -59,19 +74,32 @@ export type PermissionStatus = {
   coarseLocation: PermissionState
 }
 
+/**
+ * The individual permission aliases that can be requested with {@link requestPermissions}.
+ *
+ * `location` maps to both the coarse and fine location permissions on Android and to the standard
+ * location permission on iOS. `coarseLocation` maps to the coarse location permission only on
+ * Android, and behaves the same as `location` on iOS.
+ */
 export type PermissionType = 'location' | 'coarseLocation'
 
+/**
+ * A geolocation reading, as returned by {@link getCurrentPosition} and passed to the callback of {@link watchPosition}.
+ */
 export type Position = {
   /**
-   * Creation time for these coordinates.
+   * Creation time for these coordinates, in milliseconds since the Unix epoch.
    */
   timestamp: number
   /**
-   * The GPD coordinates along with the accuracy of the data.
+   * The GPS coordinates along with the accuracy of the data.
    */
   coords: Coordinates
 }
 
+/**
+ * Options used to configure a {@link getCurrentPosition} or {@link watchPosition} request.
+ */
 export type PositionOptions = {
   /**
    * High accuracy mode (such as GPS, if available)
@@ -92,6 +120,29 @@ export type PositionOptions = {
   maximumAge: number
 }
 
+/**
+ * Registers a callback that is invoked with the device's position whenever it changes, similar to the W3C `navigator.geolocation.watchPosition` API. Pass the returned id to {@link clearWatch} to stop watching.
+ *
+ * @example
+ * ```typescript
+ * import { watchPosition } from '@tauri-apps/plugin-geolocation';
+ * const watchId = await watchPosition(
+ *   { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 },
+ *   (position, error) => {
+ *     if (error) {
+ *       console.error(error)
+ *     } else {
+ *       console.log(position)
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @param options Configuration for the position watcher.
+ * @param cb Callback invoked with the new {@link Position} on success, or `null` and an error message when a read fails.
+ * @returns A promise resolving to the id of the registered watcher.
+ * @since 2.0.0
+ */
 export async function watchPosition(
   options: PositionOptions,
   cb: (location: Position | null, error?: string) => void
@@ -111,6 +162,19 @@ export async function watchPosition(
   return channel.id
 }
 
+/**
+ * Returns the device's current position, similar to the W3C `navigator.geolocation.getCurrentPosition` API.
+ *
+ * @example
+ * ```typescript
+ * import { getCurrentPosition } from '@tauri-apps/plugin-geolocation';
+ * const position = await getCurrentPosition();
+ * ```
+ *
+ * @param options Configuration for the position request.
+ * @returns A promise resolving to the current {@link Position}.
+ * @since 2.0.0
+ */
 export async function getCurrentPosition(
   options?: PositionOptions
 ): Promise<Position> {
@@ -119,16 +183,53 @@ export async function getCurrentPosition(
   })
 }
 
+/**
+ * Stops the position watcher registered with {@link watchPosition}.
+ *
+ * @example
+ * ```typescript
+ * import { clearWatch } from '@tauri-apps/plugin-geolocation';
+ * await clearWatch(watchId);
+ * ```
+ *
+ * @param channelId The id returned by {@link watchPosition}.
+ * @since 2.0.0
+ */
 export async function clearWatch(channelId: number): Promise<void> {
   await invoke('plugin:geolocation|clear_watch', {
     channelId
   })
 }
 
+/**
+ * Returns the current state of the geolocation permissions. Rejects if location services are disabled on the device.
+ *
+ * @example
+ * ```typescript
+ * import { checkPermissions } from '@tauri-apps/plugin-geolocation';
+ * const permission = await checkPermissions();
+ * ```
+ *
+ * @returns A promise resolving to the current {@link PermissionStatus}.
+ * @since 2.0.0
+ */
 export async function checkPermissions(): Promise<PermissionStatus> {
   return await checkPluginPermissions('geolocation')
 }
 
+/**
+ * Requests the given geolocation permissions, prompting the user if needed. Rejects if location services are disabled on the device.
+ *
+ * @example
+ * ```typescript
+ * import { requestPermissions } from '@tauri-apps/plugin-geolocation';
+ * const permission = await requestPermissions(['location']);
+ * ```
+ *
+ * @param permissions The permissions to request, or `null` to request all of them.
+ * @returns A promise resolving to the resulting {@link PermissionStatus}.
+ * @since 2.0.0
+ */
 export async function requestPermissions(
   permissions: PermissionType[] | null
 ): Promise<PermissionStatus> {

plugins/geolocation/src/desktop.rs

@@ -22,6 +22,7 @@ pub fn init<R: Runtime, C: DeserializeOwned>(
 pub struct Geolocation<R: Runtime>(AppHandle<R>);
 
 impl<R: Runtime> Geolocation<R> {
+    /// Not implemented on desktop platforms; always resolves to a default, zeroed [`Position`] without reading any real location.
     pub fn get_current_position(
         &self,
         _options: Option<PositionOptions>,
@@ -29,6 +30,7 @@ impl<R: Runtime> Geolocation<R> {
         Ok(Position::default())
     }
 
+    /// Not implemented on desktop platforms. Registers a channel for `channel_id` bookkeeping, but `callback` is never invoked with a real [`WatchEvent`].
     pub fn watch_position<F: Fn(WatchEvent) + Send + Sync + 'static>(
         &self,
         options: PositionOptions,
@@ -64,14 +66,17 @@ impl<R: Runtime> Geolocation<R> {
         Ok(())
     }
 
+    /// Not implemented on desktop platforms; always succeeds without doing anything.
     pub fn clear_watch(&self, _channel_id: u32) -> crate::Result<()> {
         Ok(())
     }
 
+    /// Not implemented on desktop platforms; always resolves to the default [`PermissionStatus`] (both permissions in the [`Prompt`](tauri::plugin::PermissionState::Prompt) state).
     pub fn check_permissions(&self) -> crate::Result<PermissionStatus> {
         Ok(PermissionStatus::default())
     }
 
+    /// Not implemented on desktop platforms; always resolves to the default [`PermissionStatus`] without prompting the user.
     pub fn request_permissions(
         &self,
         _permissions: Option<Vec<PermissionType>>,

plugins/geolocation/src/error.rs

@@ -4,13 +4,16 @@
 
 use serde::{ser::Serializer, Serialize};
 
+/// Alias for the result type returned by the geolocation APIs.
 pub type Result<T> = std::result::Result<T, Error>;
 
 // TODO: Improve Error handling (different typed errors instead of one (stringified) PluginInvokeError for all mobile errors)
 
+/// Errors that can occur while interacting with the geolocation APIs.
 #[derive(Debug, thiserror::Error)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 pub enum Error {
+    /// Forwards an error returned by the underlying Android or iOS plugin invocation.
     #[cfg(mobile)]
     #[error(transparent)]
     PluginInvoke(

plugins/geolocation/src/lib.rs

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

plugins/geolocation/src/mobile.rs

@@ -33,6 +33,7 @@ pub fn init<R: Runtime, C: DeserializeOwned>(
 pub struct Geolocation<R: Runtime>(PluginHandle<R>);
 
 impl<R: Runtime> Geolocation<R> {
+    /// Returns the device's current [`Position`]. On Android this returns the last known location immediately if it is still within `maximum_age`, otherwise it requests a fresh reading. Errors if location services are disabled or the required permission was not granted.
     pub fn get_current_position(
         &self,
         options: Option<PositionOptions>,
@@ -81,18 +82,21 @@ impl<R: Runtime> Geolocation<R> {
             .map_err(Into::into)
     }
 
+    /// Removes the position watcher registered with the given `channel_id`, as returned by [`Self::watch_position`]. Stops the platform location updates once no watcher remains.
     pub fn clear_watch(&self, channel_id: u32) -> crate::Result<()> {
         self.0
             .run_mobile_plugin("clearWatch", ClearWatchPayload { channel_id })
             .map_err(Into::into)
     }
 
+    /// Returns the current [`PermissionStatus`] for the geolocation APIs. Errors if location services are disabled on the device.
     pub fn check_permissions(&self) -> crate::Result<PermissionStatus> {
         self.0
             .run_mobile_plugin("checkPermissions", ())
             .map_err(Into::into)
     }
 
+    /// Requests the given `permissions` (or all of them when `None`) and returns the resulting [`PermissionStatus`]. Errors if location services are disabled on the device.
     pub fn request_permissions(
         &self,
         permissions: Option<Vec<PermissionType>>,

plugins/geolocation/src/models.rs

@@ -5,6 +5,7 @@
 use serde::{Deserialize, Serialize};
 use tauri::plugin::PermissionState;
 
+/// The current permission state for the geolocation APIs.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
@@ -25,6 +26,7 @@ pub struct PermissionStatus {
     pub coarse_location: PermissionState,
 }
 
+/// Options used to configure a [`get_current_position`](crate::Geolocation::get_current_position) or [`watch_position`](crate::Geolocation::watch_position) request.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
@@ -47,14 +49,18 @@ pub struct PositionOptions {
     pub maximum_age: u32,
 }
 
+/// The individual permission aliases that can be requested with [`request_permissions`](crate::Geolocation::request_permissions).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
 pub enum PermissionType {
+    /// The `location` alias. On Android this maps to both `ACCESS_COARSE_LOCATION` and `ACCESS_FINE_LOCATION`. On iOS it maps to the standard location permission.
     Location,
+    /// The `coarseLocation` alias. On Android this maps to `ACCESS_COARSE_LOCATION` only. On iOS it behaves the same as [`Location`](Self::Location).
     CoarseLocation,
 }
 
+/// The GPS coordinates of a [`Position`], along with the accuracy of each reading.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
@@ -70,12 +76,13 @@ pub struct Coordinates {
     pub altitude_accuracy: Option<f64>,
     /// The altitude the user is at, if available.
     pub altitude: Option<f64>,
-    // The speed the user is traveling, if available.
+    /// The speed the user is traveling, in meters per second, if available.
     pub speed: Option<f64>,
     /// The heading the user is facing, if available.
     pub heading: Option<f64>,
 }
 
+/// A geolocation reading, as returned by [`get_current_position`](crate::Geolocation::get_current_position) and reported through [`WatchEvent::Position`].
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(rename_all = "camelCase")]
@@ -87,10 +94,13 @@ pub struct Position {
     pub coords: Coordinates,
 }
 
+/// A single update sent through the channel callback registered with [`watch_position`](crate::Geolocation::watch_position).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[cfg_attr(feature = "specta", derive(specta::Type))]
 #[serde(untagged)]
 pub enum WatchEvent {
+    /// A new position was read successfully.
     Position(Position),
+    /// The platform failed to read a position; the string is the platform-provided error message.
     Error(String),
 }