doc: update tauri documentations (#2446)

.changes/doc-tauri-utils.md

@@ -2,4 +2,6 @@
 "tauri": minor
 ---
 
-`tauri::api` no longer re-export items in `tauri-utils`. We already expose necessary items in the root of `tauri`.
+Move items which `tauri::api` re-exports from `tauri-utils` to individual module `utils`. Because these items has their
+own Error/Result types which are not related to api module at all.
+

ARCHITECTURE.md

@@ -15,7 +15,7 @@ Tauri apps can have custom menus and have tray-type interfaces. They can be upda
 The following section briefly describes the roles of the various parts of Tauri.
 ### Tauri Core [STABLE RUST]
 #### [tauri](https://github.com/tauri-apps/tauri/tree/dev/core/tauri)
-This is the glue crate that holds everything together. It brings the runtimes, macros, utilities and API into one final product. It reads the `tauri.conf.json` file at compile time in order to bring in features and undertake actual configuration of the app (and even the `Cargo.toml` file in the project's folder). It handles script injection (for polyfills / prototype revision) at runtime, hosts the API for systems interaction, and even manages updating.
+This is the major crate that holds everything together. It brings the runtimes, macros, utilities and API into one final product. It reads the `tauri.conf.json` file at compile time in order to bring in features and undertake actual configuration of the app (and even the `Cargo.toml` file in the project's folder). It handles script injection (for polyfills / prototype revision) at runtime, hosts the API for systems interaction, and even manages updating.
 
 #### [tauri-build](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-build)
 Apply the macros at build-time in order to rig some special features needed by `cargo`.
@@ -53,24 +53,6 @@ This rust executable provides the full interface to all of the required activiti
 #### [create-tauri-app](https://github.com/tauri-apps/tauri/tree/dev/tooling/create-tauri-app) [JS]
 This is a toolkit that will enable engineering teams to rapidly scaffold out a new tauri-apps project using the frontend framework of their choice (as long as it has been configured).
 
-## TAURI RUST API
-- **app**	The App API module allows you to manage application processes.
-- **assets**	The Assets module allows you to read files that have been bundled by tauri Assets handled by Tauri during compile time and runtime.
-- **config**	The Tauri config definition.
-- **dialog**	The Dialog API module allows you to show messages and prompt for file paths.
-- **dir**	The Dir module is a helper for file system directory management.
-- **file**	The File API module contains helpers to perform file operations.
-- **http**	The HTTP request API.
-- **notification**	The desktop notifications API module.
-- **path**	The file system path operations API.
-- **process**	Process helpers including the management of child processes.
-- **rpc**	The RPC module includes utilities to send messages to the JS layer of the webview.
-- **shell**	The shell api.
-- **shortcuts**	Global shortcuts interface.
-- **version**	The semver API.
-
-
-
 # External Crates
 The Tauri-Apps organisation maintains two "upstream" crates from Tauri, namely TAO for creating and managing application windows, and WRY for interfacing with the Webview that lives within the window.
 

core/tauri-codegen/src/context.rs

@@ -97,7 +97,7 @@ pub fn context_codegen(data: ContextData) -> Result<TokenStream, EmbeddedAssetsE
     quote!(env!("CARGO_PKG_VERSION").to_string())
   };
   let package_info = quote!(
-    #root::api::PackageInfo {
+    #root::PackageInfo {
       name: #package_name,
       version: #package_version,
     }

core/tauri-codegen/src/embedded_assets.rs

@@ -304,7 +304,7 @@ impl ToTokens for EmbeddedAssets {
 
     // we expect phf related items to be in path when generating the path code
     tokens.append_all(quote! {{
-        use ::tauri::api::assets::{EmbeddedAssets, phf, phf::phf_map};
+        use ::tauri::utils::assets::{EmbeddedAssets, phf, phf::phf_map};
         EmbeddedAssets::from_zstd(phf_map! { #map })
     }});
   }

core/tauri-utils/src/config.rs

@@ -3,7 +3,8 @@
 // SPDX-License-Identifier: MIT
 
 //! The Tauri configuration used at runtime.
-//! It is pulled from a `tauri.conf.json` file and the [`config::Config`] struct is generated at compile time.
+//!
+//! It is pulled from a `tauri.conf.json` file and the [`Config`] struct is generated at compile time.
 //!
 //! # Stability
 //! This is a core functionality that is not considered part of the stable API.
@@ -648,7 +649,7 @@ mod build {
   macro_rules! literal_struct {
     ($tokens:ident, $struct:ident, $($field:ident),+) => {
       $tokens.append_all(quote! {
-        ::tauri::api::config::$struct {
+        ::tauri::utils::config::$struct {
           $($field: #$field),+
         }
       });
@@ -657,7 +658,7 @@ mod build {
 
   impl ToTokens for WindowUrl {
     fn to_tokens(&self, tokens: &mut TokenStream) {
-      let prefix = quote! { ::tauri::api::config::WindowUrl };
+      let prefix = quote! { ::tauri::utils::config::WindowUrl };
 
       tokens.append_all(match self {
         Self::App(path) => {
@@ -834,7 +835,7 @@ mod build {
 
   impl ToTokens for AppUrl {
     fn to_tokens(&self, tokens: &mut TokenStream) {
-      let prefix = quote! { ::tauri::api::config::AppUrl };
+      let prefix = quote! { ::tauri::utils::config::AppUrl };
 
       tokens.append_all(match self {
         Self::Url(url) => {
@@ -915,7 +916,7 @@ mod build {
         str_lit,
         json_value_lit,
       );
-      tokens.append_all(quote! { ::tauri::api::config::PluginConfig(#config) })
+      tokens.append_all(quote! { ::tauri::utils::config::PluginConfig(#config) })
     }
   }
 

core/tauri/src/api/cli.rs

@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-use crate::api::config::{CliArg, CliConfig};
+//! Types and functions related to CLI arguments.
+
+use crate::utils::config::{CliArg, CliConfig};
 
 use clap::{
   crate_authors, crate_description, crate_name, crate_version, App, Arg, ArgMatches, ErrorKind,
@@ -14,17 +16,16 @@ use std::collections::HashMap;
 #[macro_use]
 mod macros;
 
-/// The resolution of a arg match.
+/// The resolution of a argument match.
 #[derive(Default, Debug, Serialize)]
 #[non_exhaustive]
 pub struct ArgData {
-  /// The value of the arg.
-  /// - Value::Bool if it's a flag,
-  /// - Value::Array if it's multiple,
-  /// - Value::String if it has value,
-  /// - Value::Null otherwise.
+  /// - [`Value::Bool`] if it's a flag,
+  /// - [`Value::Array`] if it's multiple,
+  /// - [`Value::String`] if it has value,
+  /// - [`Value::Null`] otherwise.
   pub value: Value,
-  /// The number of occurrences of the arg.
+  /// The number of occurrences of the argument.
   /// e.g. `./app --arg 1 --arg 2 --arg 2 3 4` results in three occurrences.
   pub occurrences: u64,
 }
@@ -35,11 +36,11 @@ pub struct ArgData {
 pub struct SubcommandMatches {
   /// The subcommand name.
   pub name: String,
-  /// The subcommand arg matches.
+  /// The subcommand argument matches.
   pub matches: Matches,
 }
 
-/// The arg matches of a command.
+/// The argument matches of a command.
 #[derive(Default, Debug, Serialize)]
 #[non_exhaustive]
 pub struct Matches {
@@ -61,7 +62,7 @@ impl Matches {
   }
 }
 
-/// Gets the arg matches of the CLI definition.
+/// Gets the argument matches of the CLI definition.
 pub fn get_matches(cli: &CliConfig) -> crate::api::Result<Matches> {
   let about = cli
     .description()

core/tauri/src/api/dialog.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Types and functions related to display dialog.
+
 #[cfg(any(dialog_open, dialog_save))]
 use std::path::{Path, PathBuf};
 
@@ -29,6 +31,7 @@ macro_rules! run_dialog {
 }
 
 /// The file dialog builder.
+///
 /// Constructs file picker dialogs that can select single/multiple files or directories.
 #[cfg(any(dialog_open, dialog_save))]
 #[derive(Debug, Default)]

core/tauri/src/api/dir.rs

@@ -2,23 +2,24 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Types and functions related to file system directory management.
+
 use serde::Serialize;
 use std::{
   fs::{self, metadata},
   path::{Path, PathBuf},
 };
 use tempfile::{self, tempdir};
 
-/// The result of the `read_dir` function.
+/// A disk entry which is either a file or a directory.
 ///
-/// A DiskEntry is either a file or a directory.
-/// The `children` Vec is always `Some` if the entry is a directory.
+/// This is the result of the [`read_dir`]. The `children` field is always `Some` if the entry is a directory.
 #[derive(Debug, Serialize)]
 #[non_exhaustive]
 pub struct DiskEntry {
-  /// The path to this entry.
+  /// The path to the entry.
   pub path: PathBuf,
-  /// The name of this entry (file name with extension or directory name)
+  /// The name of the entry (file name with extension or directory name).
   pub name: Option<String>,
   /// The children of this entry if it's a directory.
   #[serde(skip_serializing_if = "Option::is_none")]
@@ -59,7 +60,7 @@ pub fn read_dir<P: AsRef<Path>>(path: P, recursive: bool) -> crate::api::Result<
   Result::Ok(files_and_dirs)
 }
 
-/// Runs a closure with a temp dir argument.
+/// Runs a closure with a temporary directory argument.
 pub fn with_temp_dir<F: FnOnce(&tempfile::TempDir)>(callback: F) -> crate::api::Result<()> {
   let dir = tempdir()?;
   callback(&dir);

core/tauri/src/api/file.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Types and functions related to file operations.
+
 mod extract;
 mod file_move;
 

core/tauri/src/api/file/extract.rs

@@ -26,7 +26,7 @@ pub enum Compression {
   Gz,
 }
 
-/// The extract manager.
+/// The extract manager to retrieve files from archives.
 #[derive(Debug)]
 pub struct Extract<'a> {
   source: &'a path::Path,

core/tauri/src/api/http.rs

@@ -2,20 +2,22 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+//! Types and functions related to HTTP request.
+
 use http::{header::HeaderName, Method};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use serde_repr::{Deserialize_repr, Serialize_repr};
 
 use std::{collections::HashMap, path::PathBuf, time::Duration};
 
-/// Client builder.
+/// The builder of [`Client`].
 #[derive(Debug, Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ClientBuilder {
-  /// Max number of redirections to follow
+  /// Max number of redirections to follow.
   pub max_redirections: Option<usize>,
-  /// Connect timeout in seconds for the request
+  /// Connect timeout in seconds for the request.
   pub connect_timeout: Option<u64>,
 }
 
@@ -61,7 +63,7 @@ impl ClientBuilder {
   }
 }
 
-/// The HTTP client.
+/// The HTTP client based on [`reqwest`].
 #[cfg(feature = "reqwest-client")]
 #[derive(Debug, Clone)]
 pub struct Client(reqwest::Client);
@@ -75,8 +77,8 @@ pub struct Client(ClientBuilder);
 impl Client {
   /// Executes an HTTP request
   ///
-  /// The response will be transformed to String,
-  /// If reading the response as binary, the byte array will be serialized using serde_json.
+  /// The response will be transformed to String.
+  /// If reading the response as binary, the byte array will be serialized using [`serde_json`].
   pub async fn send(&self, request: HttpRequestBuilder) -> crate::api::Result<Response> {
     let method = Method::from_bytes(request.method.to_uppercase().as_bytes())?;
 
@@ -132,7 +134,7 @@ impl Client {
 impl Client {
   /// Executes an HTTP request
   ///
-  /// The response will be transformed to String,
+  /// The response will be transformed to String.
   /// If reading the response as binary, the byte array will be serialized using serde_json.
   pub async fn send(&self, request: HttpRequestBuilder) -> crate::api::Result<Response> {
     let method = Method::from_bytes(request.method.to_uppercase().as_bytes())?;
@@ -188,7 +190,7 @@ impl Client {
 #[derive(Serialize_repr, Deserialize_repr, Clone, Debug)]
 #[repr(u16)]
 #[non_exhaustive]
-/// The request's response type
+/// The HTTP response type.
 pub enum ResponseType {
   /// Read the response as JSON
   Json = 1,
@@ -198,7 +200,7 @@ pub enum ResponseType {
   Binary,
 }
 
-/// FormBody data types.
+/// [`FormBody`] data types.
 #[derive(Debug, Deserialize)]
 #[serde(untagged)]
 #[non_exhaustive]
@@ -290,7 +292,7 @@ impl HttpRequestBuilder {
     }
   }
 
-  /// Sets the request params.
+  /// Sets the request parameters.
   pub fn query(mut self, query: HashMap<String, String>) -> Self {
     self.query = Some(query);
     self
@@ -390,7 +392,7 @@ pub struct RawResponse {
   pub data: Vec<u8>,
 }
 
-/// The response type.
+/// The response data.
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]

core/tauri/src/api/mod.rs

@@ -6,27 +6,17 @@
 #![warn(missing_docs)]
 // #![feature(const_int_pow)]
 
-/// A module for working with processes.
 pub mod dialog;
-/// The Dir module is a helper for file system directory management.
 pub mod dir;
-/// The File API module contains helpers to perform file operations.
 pub mod file;
-/// The HTTP request API.
 pub mod http;
-/// The file system path operations API.
 pub mod path;
-/// The Command API module allows you to manage child processes.
 pub mod process;
-/// The RPC module includes utilities to send messages to the JS layer of the webview.
 pub mod rpc;
-/// The shell api.
 #[cfg(shell_open)]
 pub mod shell;
-/// The semver API.
 pub mod version;
 
-/// The CLI args interface.
 #[cfg(feature = "cli")]
 #[cfg_attr(doc_cfg, doc(cfg(feature = "cli")))]
 pub mod cli;
@@ -35,18 +25,14 @@ pub mod cli;
 #[cfg_attr(doc_cfg, doc(cfg(feature = "cli")))]
 pub use clap;
 
-/// The desktop notifications API module.
 #[cfg(notification_all)]
 pub mod notification;
 
-#[doc(hidden)]
-pub use tauri_utils::*;
-
 mod error;
 
-/// Tauri API error.
+/// The error type of Tauri API module.
 pub use error::Error;
-/// Tauri API result type.
+/// The result type of Tauri API module.
 pub type Result<T> = std::result::Result<T, Error>;
 
 // Not public API
@@ -55,9 +41,9 @@ pub mod private {
   pub use once_cell::sync::OnceCell;
 
   pub trait AsTauriContext {
-    fn config() -> &'static crate::api::config::Config;
-    fn assets() -> &'static crate::api::assets::EmbeddedAssets;
+    fn config() -> &'static crate::Config;
+    fn assets() -> &'static crate::utils::assets::EmbeddedAssets;
     fn default_window_icon() -> Option<&'static [u8]>;
-    fn package_info() -> crate::api::PackageInfo;
+    fn package_info() -> crate::PackageInfo;
   }
 }