doc: update tauri documentations (#2446)

Author: Ngo Iok Ui (Wu Yu Wei)

.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,